Algorand Remote MCP

A Model Context Protocol (MCP) server implementation that provides tools and resources for AI agents to interact with the Algorand blockchain.

Overview

Algorand Remote MCP bridges the gap between AI agents and the Algorand blockchain ecosystem. It serves as a middleware layer that enables AI systems to interact with blockchain technology through a standardized interface, without requiring deep blockchain expertise.

The server is designed to run on Cloudflare Workers and provides a comprehensive set of tools and resources for blockchain operations, including wallet management, transaction creation and submission, API integration, and knowledge access. This is a remote MCP implementation only, focused on providing server-side functionality for AI agents to interact with the Algorand blockchain.

Features

Secure Wallet Management: Create, access, and manage Algorand wallets with automatic wallet creation for new users
HashiCorp Vault Integration:
- Secure storage of sensitive wallet credentials using HashiCorp Vault
- Ed25519 keypair operations for cryptographic functions
- Policy that all new accounts use Ed25519 secure secrets engine.
Comprehensive Transaction Support: Create, sign, and submit various transaction types (payments, assets, applications)
API Integration: Access Algorand node, indexer, and NFD APIs through standardized interfaces
Knowledge Resources: Access documentation and guides for Algorand development
Google OAuth Authentication: Secure user authentication through Google OAuth
Pagination Support: Handle large datasets with built-in pagination
Standardized Response Formatting: Consistent response formatting for AI agent consumption
Wallet Reset Capability: Users can reset their wallet and generate a new one if needed

Installation

Make sure you have these:

Node.js v16+ installed
A Google account for OAuth authentication

Add this to your MCP servers:

{
  "mcpServers": {
    "algorand-remote-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://algorand-remote-mcp.your-account.workers.dev/sse"  // or http://localhost:8787/sse for local development
      ]
    }
  }
}

And then restart your LLM Agent and prompt to it:

Read Algorand Remote MCP guide.

Architecture

Algorand Remote MCP is built on the Model Context Protocol (MCP), which provides a standardized way for AI agents to interact with external systems. The server is implemented as a Cloudflare Worker with the following components:

AlgorandRemoteMCP Class: Main MCP agent implementation that extends McpAgent
Tool Managers: Specialized managers for different operation types
Resource Providers: URI-based access to data and documentation
ResponseProcessor: Standardized response formatting with pagination support
OAuth Integration: Secure user authentication and authorization
HashiCorp Vault Integration:
- Secure storage of sensitive wallet credentials
- Ed25519 keypair operations for cryptographic functions
- Secure key management without exposing private keys
- Policy that all new accounts use the secure Ed25519 secrets engine
Service Bindings: Inter-worker communication for secure vault operations

Available Tools

Account Management

create_account: Create a new Algorand account
mnemonic_to_address: View the address associated with a mnemonic (without storing the private key)
check_account_balance: Check the balance of an Algorand account

Wallet Management

get_wallet_address: Get the address for the configured wallet
get_wallet_info: Get account information for the configured wallet
get_wallet_assets: Get assets owned by the configured wallet
get_wallet_publickey: Get the public key for the configured wallet
reset_wallet_account: Reset the wallet account for the configured user

Transaction Management

create_payment_transaction: Create a payment transaction
sign_transaction: Sign a transaction with the wallet's credentials
submit_transaction: Submit a signed transaction to the network
create_atomic_group: Create an atomic transaction group from multiple transactions
sign_atomic_group: Sign an atomic transaction group
submit_atomic_group: Submit a signed atomic transaction group to the network
asset_optin: Create an asset opt-in transaction
transfer_asset: Create an asset transfer transaction
create_asset: Create a new Algorand Standard Asset
create_application: Create a new smart contract application
call_application: Call a smart contract application

API Integration

api_algod_get_account_info: Get account details from Algorand node
api_algod_get_transaction_info: Get transaction details from Algorand node
api_indexer_lookup_account_by_id: Get account details from indexer
api_nfd_get_nfd: Get NFD address information

Utility Tools

validate_address: Validate an Algorand address
encode_obj: Encode an object to msgpack format
decode_obj: Decode msgpack bytes to an object
compile_teal: Compile TEAL source code
algorand_mcp_guide: Access comprehensive guide for using Algorand Remote MCP

Cryptographic Tools

create_keypair: Create a new Ed25519 keypair in HashiCorp Vault
get_public_key: Get the public key for a keypair from HashiCorp Vault
sign_bytes: Sign bytes with a secret key
verify_signature: Verify a signature using a keypair in HashiCorp Vault

Available Resources

Wallet Resources

algorand://wallet/address: Wallet account address
algorand://wallet/account: Wallet account information
algorand://wallet/assets: Wallet account assets
algorand://wallet/publickey: Wallet account public key

Knowledge Resources

algorand://knowledge/taxonomy: Full taxonomy of knowledge resources
algorand://knowledge/taxonomy/{category}: Category-specific knowledge resources

Guide Resources

algorand://remote-mcp-guide: Comprehensive guide for using Algorand Remote MCP

Installation and Setup

Development Prerequisites

Node.js v16+
Cloudflare Workers account
Algorand node access (or use a service like Nodely.io aka AlgoNode)
Google OAuth credentials
HashiCorp Vault worker for secure credential storage

Environment Variables

ALGORAND_NETWORK=mainnet
ALGORAND_ALGOD=https://your-algod-node.com
ALGORAND_INDEXER=https://your-indexer-node.com
NFD_API_URL=https://api.nf.domains
ALGORAND_TOKEN=your-api-token
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
HCV_WORKER_URL=https://your-hashicorp-vault-worker.workers.dev

Deployment

Clone the repository
Install dependencies: npm install
Configure environment variables in wrangler.toml
Deploy to Cloudflare Workers: wrangler deploy

Usage

Authentication Flow for users

User authenticates through Google OAuth
Server creates or retrieves wallet credentials from HashiCorp Vault
User can now access tools and resources through the MCP interface

Transaction Flow for Agents

Individual Transactions

Create transaction using appropriate tool (e.g., create_payment_transaction)
Sign transaction with wallet credentials using sign_transaction
Submit transaction to network using submit_transaction
Verify transaction success

Atomic Transaction Groups

Create multiple transactions as an atomic group using create_atomic_group
Sign the transaction group using sign_atomic_group
Submit the signed group to the network using submit_atomic_group
Verify transaction success

Project Structure

├── src/                          # Source code directory
│   ├── index.ts                  # Main entry point
│   ├── types.ts                  # Type definitions
│   ├── oauth-handler.ts          # OAuth authentication handler
│   ├── workers-oauth-utils.ts    # OAuth utilities
│   ├── resources/                # Resource providers
│   │   ├── guide/                # Guide resources
│   │   ├── knowledge/            # Knowledge resources
│   │   └── wallet/               # Wallet resources
│   ├── tools/                    # Tool managers
│   │   ├── accountManager.ts     # Account management tools
│   │   ├── algodManager.ts       # Algorand node tools
│   │   ├── arc26Manager.ts       # ARC-26 tools
│   │   ├── knowledgeManager.ts   # Knowledge tools
│   │   ├── utilityManager.ts     # Utility tools
│   │   ├── walletManager.ts      # Wallet management tools
│   │   ├── apiManager/           # API integration tools
│   │   └── transactionManager/   # Transaction tools
│   └── utils/                    # Utilities
│       ├── Guide.js              # Guide content
│       ├── oauth-utils.ts        # OAuth utilities
│       ├── vaultManager.ts       # HashiCorp Vault utilities for secret storage and cryptographic operations
│       └── responseProcessor.ts  # Response formatting

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch: git checkout -b feature/my-new-feature
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature/my-new-feature
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Algorand Remote MCP Tools and Resources

MCP Server Information

Server Name: algorand-remote-mcp
Connection: npx mcp-remote https://algorand-remote-mcp.emg110.workers.dev/sse

Tools full index

Cryptographic and Encoding Tools

validate_address - Check if an Algorand address is valid
encode_address - Encode a public key to an Algorand address
decode_address - Decode an Algorand address to a public key
get_application_address - Get the address for a given application ID
bytes_to_bigint - Convert bytes to a BigInt
bigint_to_bytes - Convert a BigInt to bytes
encode_uint64 - Encode a uint64 to bytes
decode_uint64 - Decode bytes to a uint64
verify_bytes - Verify a signature against bytes with an Algorand address
sign_bytes - Sign bytes with a secret key
encode_obj - Encode an object to msgpack format
decode_obj - Decode msgpack bytes to an object

Account Management

create_account - Create a new Algorand account
mnemonic_to_address - View the address associated with a mnemonic (without storing the private key)
check_account_balance - Check the balance of an Algorand account
get_wallet_publickey - Get the public key for the configured wallet
get_wallet_address - Get the address for the configured wallet
get_wallet_info - Get the account information for the configured wallet
get_wallet_assets - Get the assets for the configured wallet
reset_wallet_account - Reset the wallet account for the configured user

Transaction Operations

create_payment_transaction - Create a payment transaction on Algorand
sign_transaction - Sign an Algorand transaction with your agent account
submit_transaction - Submit a signed transaction to the Algorand network
create_key_registration_transaction - Create a key registration transaction
assign_group_id - Assign a group ID to a set of transactions for atomic execution
create_atomic_group - Create an atomic transaction group from multiple transactions of types pay, axfer, acfg, appl, afrz or keyreg
sign_atomic_group - Sign an atomic transaction group
submit_atomic_group - Submit a signed atomic transaction group to the Algorand network
send_raw_transaction - Submit signed transactions to the Algorand network
simulate_raw_transactions - Simulate raw transactions
simulate_transactions - Simulate encoded transactions

Asset Operations

create_asset - Create a new Algorand Standard Asset (ASA)
asset_optin - Opt-in to an Algorand Standard Asset (ASA)
transfer_asset - Transfer an Algorand Standard Asset (ASA)

Application (Smart Contract) Operations

create_application - Create a new smart contract application on Algorand
update_application - Update an existing smart contract application
delete_application - Delete an existing smart contract application
closeout_application - Close out from an Algorand application
clear_application - Clear state for an Algorand application
call_application - Call a smart contract application on Algorand
optin_application - Opt-in to an Algorand application

TEAL Operations

compile_teal - Compile TEAL source code
disassemble_teal - Disassemble TEAL bytecode into source code

URI Generation

generate_algorand_uri - Generate a URI following the ARC-26 specification

API Access

api_algod_get_account_info - Get current account balance, assets, and auth address from algod
api_algod_get_account_application_info - Get account-specific application information
api_algod_get_account_asset_info - Get account-specific asset information
api_algod_get_application_info - Get application details from algod
api_algod_get_application_box_value - Get application box contents
api_algod_get_application_boxes - Get all application boxes
api_algod_get_application_state - Get application global state
api_algod_get_asset_info - Get asset details from algod
api_algod_get_asset_holding - Get asset holding information for an account
asset_verification_status - Get the verification status of an Algorand asset from Pera Wallet
asset_details_info - Get detailed information about an Algorand asset from Pera Wallet
api_algod_get_transaction_info - Get transaction details by transaction ID
api_algod_get_pending_transactions - Get pending transactions from algod mempool

Indexer API Access

api_indexer_lookup_account_by_id - Get account information from indexer
api_indexer_lookup_account_assets - Get account assets
api_indexer_lookup_account_app_local_states - Get account application local states
api_indexer_lookup_account_created_applications - Get applications created by an account
api_indexer_search_for_accounts - Search for accounts with various criteria
api_indexer_lookup_applications - Get application information from indexer
api_indexer_lookup_application_logs - Get application log messages
api_indexer_search_for_applications - Search for applications with various criteria
api_indexer_lookup_application_box - Get application box by name
api_indexer_lookup_application_boxes - Get all application boxes
api_indexer_lookup_asset_by_id - Get asset information from indexer
api_indexer_lookup_asset_balances - Get accounts that hold a specific asset
api_indexer_search_for_assets - Search for assets with various criteria
api_indexer_lookup_transaction_by_id - Get transaction details from indexer
api_indexer_lookup_account_transactions - Get transactions related to an account
api_indexer_search_for_transactions - Search for transactions with various criteria
api_indexer_search - Search the Algorand indexer for accounts, transactions, assets, or applications

NFD (Algorand Name Service) Operations

api_nfd_get_nfd - Get NFD domain information by name
api_nfd_get_nfds_for_address - Get all NFD domains owned by an address
api_nfd_get_nfd_activity - Get activity for an NFD domain
api_nfd_get_nfd_analytics - Get analytics for an NFD domain
api_nfd_browse_nfds - Browse NFD domains with filtering options
api_nfd_search_nfds - Search for NFD domains

General API and Documentation

api_request - Make a request to an external API
algorand_mcp_guide - Access comprehensive guide for using Algorand Remote MCP
get_knowledge_doc - Get markdown content for specified knowledge documents
list_knowledge_docs - List available knowledge documents by category

Resources full index

Algorand Wallet Resources

algorand://wallet/publickey - Wallet Account Public Key
algorand://wallet/address - Wallet Account Address
algorand://wallet/account - Wallet Account Information
algorand://wallet/assets - Wallet Account Assets

Algorand Knowledge Resources

algorand://knowledge/taxonomy - Algorand Knowledge Full Taxonomy
algorand://knowledge/taxonomy/arcs - Algorand Request for Comments
algorand://knowledge/taxonomy/sdks - Software Development Kits
algorand://knowledge/taxonomy/algokit - AlgoKit
algorand://knowledge/taxonomy/algokit-utils - AlgoKit Utils
algorand://knowledge/taxonomy/tealscript - TEALScript
algorand://knowledge/taxonomy/puya - Puya
algorand://knowledge/taxonomy/liquid-auth - Liquid Auth
algorand://knowledge/taxonomy/python - Python Development
algorand://knowledge/taxonomy/developers - Developer Documentation
algorand://knowledge/taxonomy/clis - CLI Tools
algorand://knowledge/taxonomy/nodes - Node Management
algorand://knowledge/taxonomy/details - Developer Details