<div align="center">

⛓️ 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

</div>

---

🚀 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

---

<div align="center">

Built by Tairon.ai team with help from Claude

</div>