Algorand MCP Server

⛓️ Algorand MCP Server v0.1

Production-ready Model Context Protocol (MCP) server for
Algorand blockchain integration

Features • Quick Start • Tools • Examples • Prompts • Use Cases • Security

🚀 Features

⚡ Algorand Blockchain Integration

10,000 TPS - Lightning-fast transaction processing
Instant Finality - Transactions confirmed in ~3.3 seconds
Pure Proof-of-Stake - Energy-efficient consensus mechanism
Low Fees - Minimal transaction costs (~0.001 ALGO)
No Forks - Guaranteed transaction finality

🛠️ Core Capabilities

Account Management - Create, import, and query Algorand accounts
Transactions - Send payments, search transactions, track confirmations
Asset Operations (ASA) - Create and manage Algorand Standard Assets
NFT Support - Mint and transfer unique assets (total=1)
Token Balances - Check balances for any ASA including USDC, USDT, etc.
Network Monitoring - Real-time blockchain status and metrics
Staking Info - Query account participation and rewards status

🔧 Developer Tools

40+ Asset Symbols - Built-in mapping for popular Algorand tokens
Multi-Network Support - Seamless mainnet/testnet switching
Explorer Integration - Direct links to Lora and Pera explorers
Environment Configuration - Easy account setup via .env
No Private Key Required - Many operations work with just addresses

🏛️ Enterprise-Ready

Built with official Algorand SDK
Comprehensive error handling
Automatic network selection (mainnet/testnet)
Docker containerization support
MCP protocol implementation
25 specialized blockchain tools
Multi-explorer support (Lora, Pera)

📦 Quick Start

✅ Prerequisites

# Required
Node.js >= 18.0.0
npm >= 9.0.0

📥 Installation

# Clone the repository
git clone https://github.com/Tairon-ai/algorand-mcp.git
cd algorand-mcp

# Install dependencies
npm install

# Configure environment (optional)
cp .env.example .env
# Edit .env to set network preference
# See GETTING_ALGO.md for how to get ALGO tokens

# Start the server
npm start

# Development mode
npm run dev

# MCP stdio server for Claude Desktop
npm run mcp

🤖 Claude Desktop Integration

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "algorand": {
      "command": "node",
      "args": ["/path/to/algorand-mcp/mcp/index.js"],
      "env": {
        "ALGORAND_NETWORK": "mainnet",
        "ALGORAND_ACCOUNT_MNEMONIC": "your 25 word mnemonic phrase if needed",
        "ALGORAND_NODE_URL": "https://mainnet-api.algonode.cloud",
        "ALGORAND_INDEXER_URL": "https://mainnet-idx.algonode.cloud"
      }
    }
  }
}

🛠 Available Tools

👤 Account Operations

Tool	Description	Key Parameters
`getAccountInfo`	Get account balance, assets, and applications. Uses configured account if no address provided	`address` (optional)
`generateAccount`	Create new Algorand account with mnemonic	-
`importAccount`	Import account from 25-word mnemonic	`mnemonic`
`getAccountAssets`	List all assets held by an account	`address`
`getAccountHistory`	Get transaction history for account	`address`, `limit`
`getStakingInfo`	Get staking rewards and participation info	`address`

💸 Transaction Operations

Tool	Description	Key Parameters
`sendPayment`	Send ALGO payment (auto-uses configured account if no key)	`to`, `amount`, `from` (optional), `privateKey` (optional)
`getTransaction`	Get transaction details by ID	`txId`
`searchTransactions`	Search with filters	`address`, `minAmount`, `maxAmount`, `assetId`
`waitForConfirmation`	Wait for transaction confirmation	`txId`, `timeout`

🪙 Asset Operations (ASA)

Tool	Description	Key Parameters
`createAsset`	Create new Algorand Standard Asset	`name`, `unitName`, `total`, `decimals`, `from`, `privateKey`
`getAssetInfo`	Get asset details and parameters	`assetId`
`getAssetBySymbol`	Get asset info by symbol (USDC, USDT, etc.)	`symbol`
`getAvailableAssets`	List all available asset symbols with IDs	-
`getAssetBalance`	Get balance of specific asset for account	`address`, `assetId` or `symbol`

🎨 NFT Operations

Tool	Description	Key Parameters
`mintNFT`	Create new NFT (unique asset with total=1)	`name`, `unitName`, `from`, `privateKey`, `url`, `metadataHash`
`transferNFT`	Transfer NFT/asset ownership	`assetId`, `from`, `to`, `privateKey`

📊 Network Operations

Tool	Description	Key Parameters
`getNetworkStatus`	Get blockchain status and metrics	-
`getCurrentBlock`	Get latest block information	-
`getBlock`	Get specific block details	`round`

🔧 Utility Tools

Tool	Description	Key Parameters
`getExplorerUrls`	Get explorer URLs for any entity	`type` (account/asset/transaction/block), `id`

📜 Smart Contract Operations (Advanced)

Tool	Description	Key Parameters
`deployContract`	Deploy compiled TEAL smart contract	`approval`, `clear`, `creator`, `privateKey`
`callContract`	Call smart contract method	`appId`, `sender`, `privateKey`, `appArgs`
`getContractState`	Read contract global/local state	`appId`, `address` (for local)

💡 Examples

Note on Transactions: To send ALGO or create assets, you need either:
A configured account in .env with ALGORAND_ACCOUNT_MNEMONIC
Or provide the private key directly in the transaction parameters
For read-only operations (balance checks, asset info), only addresses are needed.

🏦 Create and Fund Account

// Generate new account
{
  "tool": "generateAccount"
}
// Returns: address, privateKey, mnemonic

// Check balance
{
  "tool": "getAccountInfo",
  "params": {
    "address": "ALGORAND_ADDRESS_HERE"
  }
}

// Send payment with test account (automatic)
{
  "tool": "sendPayment",
  "params": {
    "to": "RECIPIENT_ADDRESS",
    "amount": 10.5,
    "note": "Payment from test account"
  }
}

// Send payment with specific account
{
  "tool": "sendPayment",
  "params": {
    "from": "SENDER_ADDRESS",
    "to": "RECIPIENT_ADDRESS",
    "amount": 10.5,
    "privateKey": "base64_encoded_private_key"
  }
}

🪙 Create and Manage Assets

// Create fungible token
{
  "tool": "createAsset",
  "params": {
    "from": "CREATOR_ADDRESS",
    "name": "My Token",
    "unitName": "MTK",
    "total": 1000000,
    "decimals": 6,
    "privateKey": "base64_encoded_private_key"
  }
}

// Get asset information by ID
{
  "tool": "getAssetInfo",
  "params": {
    "assetId": 123456789
  }
}

// Get asset by symbol (e.g., USDC)
{
  "tool": "getAssetBySymbol",
  "params": {
    "symbol": "USDC"
  }
}

// List all available assets
{
  "tool": "getAvailableAssets"
}

🎨 NFT Operations

// Mint NFT
{
  "tool": "mintNFT",
  "params": {
    "from": "CREATOR_ADDRESS",
    "name": "Algo Punk #001",
    "unitName": "APUNK",
    "url": "ipfs://QmXxx...",
    "privateKey": "base64_encoded_private_key",
    "metadataHash": "optional_metadata_hash"
  }
}

// Transfer NFT/Asset
{
  "tool": "transferAsset",
  "params": {
    "assetId": 987654321,
    "from": "OWNER_ADDRESS",
    "to": "BUYER_ADDRESS",
    "privateKey": "base64_encoded_private_key"
  }
}

🔍 Search and Analytics

// Search transactions by address
{
  "tool": "searchTransactions",
  "params": {
    "address": "YOUR_ALGORAND_ADDRESS",
    "limit": 50
  }
}

// Search transactions by amount range
{
  "tool": "searchTransactions",
  "params": {
    "minAmount": 10,
    "maxAmount": 1000,
    "limit": 50
  }
}

// Search asset transactions
{
  "tool": "searchTransactions",
  "params": {
    "assetId": 31566704,
    "limit": 20
  }
}

// Get network status
{
  "tool": "getNetworkStatus"
}

// Get account history
{
  "tool": "getAccountHistory",
  "params": {
    "address": "ALGORAND_ADDRESS",
    "limit": 100
  }
}

// Get configured account info from environment
{
  "tool": "getAccountInfo"
  // No params needed - uses env account
}

// Get asset balance for specific token
{
  "tool": "getAssetBalance",
  "params": {
    "address": "ALGORAND_ADDRESS",
    "symbol": "USDC"
  }
}

// Get ALGO balance
{
  "tool": "getAssetBalance",
  "params": {
    "address": "ALGORAND_ADDRESS",
    "assetId": 0
  }
}

// Get explorer URLs for viewing on blockchain explorer
{
  "tool": "getExplorerUrls",
  "params": {
    "type": "account",
    "id": "ALGORAND_ADDRESS"
  }
}

🤖 Prompts

💬 Example Prompts for AI Assistants

🏦 Account Management

"Create a new Algorand account with mnemonic"
"Check balance for address ABC123..."
"Import my account from mnemonic phrase"
"Show all assets in wallet XYZ789..."
"Get transaction history for my account"
"Generate 5 new Algorand wallets"
"Get staking info for address ABC123..."
"Show my configured account details"
"Get account information with all assets"

💸 Transactions

"Send 1 ALGO from my configured account to [ADDRESS]"
"Generate new account and send it 2 ALGO from configured account"
"Show how to send payment with private key"
"Search transactions for address [YOUR_ADDRESS]"
"Get my configured account info and transaction history"
"Find all transactions from/to address [ADDRESS]"
"Get transaction details for txId ABC..."
"Wait for transaction confirmation"
"Search transactions with amount greater than 1 ALGO"
"Find transactions with asset ID 31566704"
"Send micropayment of 0.001 ALGO to [ADDRESS]"
"Get explorer URLs for transaction [TXID]"

🪙 Asset Operations (ASA)

"Create a new token with 1 million supply"
"Mint fungible token MTK with 6 decimals"
"Get info about asset ID 123456"
"Get USDC asset details"
"Show me info for USDT token"
"List all available asset symbols"
"What assets can I query by symbol?"
"Create loyalty points token with 0 decimals"
"Get asset info for YLDY token"
"Find asset ID for TINY token"
"Get ALGO token information"
"Show USDC_TESTNET details on testnet"
"Check USDC balance for account ABC123..."
"Get my ALGO balance"
"Show USDT balance for address XYZ789..."
"Check token balance by asset ID 31566704"

🎨 NFT Operations

"Mint an NFT called 'Algo Punk #001'"
"Transfer NFT asset ID 789 to buyer address"
"Mint NFT with IPFS url ipfs://QmXyz..."
"Get NFT info for asset ID 12345"
"Check NFT balance for address"
"Transfer my NFT to [ADDRESS]"
"Create unique NFT with metadata hash"
"Get explorer URLs for NFT asset"

🌐 Network & Blockchain

"Get current Algorand network status"
"Show latest block information"
"Get block details for round 30000000"
"Show current block round and timestamp"
"Get explorer URLs for block 45000000"
"Check which network we're connected to"
"Get latest confirmed round information"

🔧 Development & Testing

"Get my configured account details"
"Show configured account from environment"
"Get explorer URL for transaction ABC..."
"Show block explorer link for account XYZ..."
"Get explorer URLs for asset 31566704"
"Show Lora and Pera explorer links for my transaction"
"Get testnet explorer URLs for my account"

🎯 Use Cases

💰 Token Management

Create and manage fungible tokens
Check token balances across accounts
Track USDC, USDT and other ASA holdings
Monitor token transactions
Query asset information

🎨 NFT Operations

Mint unique digital assets
Transfer NFT ownership
Track NFT provenance
Store IPFS metadata references
Manage digital collectibles

💸 Payment Processing

Send ALGO payments programmatically
Batch payment processing
Micropayments and tips
Transaction tracking and confirmation
Payment history analysis

📊 Portfolio Tracking

Monitor account balances
Track multiple assets
View transaction history
Check staking participation
Generate account reports

🔍 Blockchain Analytics

Search transactions by various criteria
Monitor network status
Track block production
Analyze transaction patterns
Generate explorer links

🏗️ Development & Testing

Rapid prototyping with testnet
Account generation for testing
Asset creation for demos
Transaction testing and verification
Integration with AI assistants

🔒 Security

🛡️ Security Features

Private Key Management - Never expose keys, use secure storage
Network Verification - Always confirm mainnet vs testnet
Transaction Validation - Verify all parameters before signing
Input Sanitization - All inputs validated and sanitized
Environment Variables - Secure credential storage
Optional Private Keys - Many read operations don't need keys

🔐 Best Practices

// DO: Use environment variables
const mnemonic = process.env.ALGORAND_ACCOUNT_MNEMONIC;

// DON'T: Hardcode sensitive data
const privateKey = "abc123..."; // Never do this!

// DO: Validate addresses before operations
if (!algosdk.isValidAddress(address)) {
  throw new Error("Invalid address");
}

// DO: Use configured account for convenience
// No need to pass privateKey for every transaction
{
  "tool": "sendPayment",
  "params": {
    "to": "RECIPIENT",
    "amount": 1
    // privateKey automatically used from env
  }
}

📊 Network Information

🌐 Networks

Network	Purpose	API Endpoint
MainNet	Production	`https://mainnet-api.algonode.cloud`
TestNet	Testing	`https://testnet-api.algonode.cloud`
BetaNet	Beta features	`https://betanet-api.algonode.cloud`

⚡ Performance Metrics

Block Time: ~3.3 seconds
TPS: 10,000 transactions per second
Finality: Instant (no rollbacks)
Min Balance: 0.1 ALGO
Min Fee: 0.001 ALGO

🚀 Deployment

🏭 Production Deployment

# Using PM2
pm2 start mcp/index.js --name algorand-mcp

# Using Docker
docker build -t algorand-mcp .
docker run -d -p 3000:3000 --env-file .env algorand-mcp

# Using Docker Compose
docker-compose up -d

🔑 Environment Variables

# Network Configuration
ALGORAND_NETWORK=mainnet  # or testnet, betanet

# Server Configuration
PORT=3000
NODE_ENV=production

# Optional: Test Account (for development/testing)
# ⚠️ NEVER commit real mainnet credentials!
# 📖 See GETTING_ALGO.md for how to get ALGO
# ALGORAND_ACCOUNT_ADDRESS=YOUR_ADDRESS_HERE
# ALGORAND_ACCOUNT_MNEMONIC="25 word mnemonic phrase"

# Optional: Custom node endpoints (if not using default AlgoNode)
# ALGORAND_NODE_URL=https://mainnet-api.algonode.cloud
# ALGORAND_INDEXER_URL=https://mainnet-idx.algonode.cloud

💰 Getting ALGO for Testing

TestNet: Get free ALGO from TestNet Dispenser
MainNet: Buy ALGO from exchanges (Coinbase, Binance, etc.)
Full Guide: See GETTING_ALGO.md for detailed instructions

📚 Resources

📖 Documentation

Algorand Developer Portal - Official developer docs
Algorand SDK Docs - SDK documentation
MCP Protocol - Model Context Protocol specs
Algorand API Reference - REST API docs

🛠️ Development Tools

AlgoNode - Free Algorand API service (used by this MCP)
Algorand SDK (JavaScript) - JS SDK we use
Node.js - JavaScript runtime required

🌍 Ecosystem

Pera Wallet - Official Algorand wallet
TestNet Dispenser - Get free test ALGO
Algorand Foundation - Official foundation

🔍 Block Explorers

Lora Explorer (MainNet) - Official AlgoKit explorer
Pera Explorer (MainNet) - Beautiful UI explorer
Lora Explorer (TestNet) - TestNet explorer
Pera Explorer (TestNet) - TestNet with modern UI

Note: Explorer URLs are automatically included in all API responses via getExplorerUrls tool

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

# Fork and clone
git clone https://github.com/Tairon-ai/algorand-mcp
cd algorand-mcp

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
npm test

# Submit pull request
git push origin feature/amazing-feature

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Algorand Foundation - Blockchain technology
Algorand Inc. - Core development
AlgoKit - Development tools
Model Context Protocol - AI integration standard

Built by Tairon.ai team with help from Claude

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables interaction with the Algorand blockchain through 25+ specialized tools for account management, payments, asset creation, NFT operations, and network monitoring. Supports both mainnet and testnet with instant finality and low fees.