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

# 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

{
  "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"
      }
    }
  }
}

// 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 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"
}

// 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 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"
  }
}

"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"

"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]"

"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"

"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"

"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"

"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"

// 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
  }
}

# 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

# 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

# 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