Algorand MCP Server v0.1.1

A comprehensive Model Context Protocol (MCP) server providing 50+ tools for Algorand blockchain development, including account management, asset operations, smart contracts, API integration, swap functionality, and advanced transaction capabilities.

⭐ New in v0.1: Added swap functionality with Pera Swap integration and a complete Raycast extension for native macOS integration!

🎥 Project Demo

Watch here: https://youtu.be/2MtLTSmOi5Y

🚀 What's Included

This repository contains two powerful tools for Algorand development:

1. 🤖 MCP Server - AI assistant integration with 50+ blockchain tools
2. ⚡ Raycast Extension - Native macOS toolbar integration for Algorand operations

Overview

This MCP server provides a complete suite of tools for AI assistants to interact with the Algorand blockchain, from basic operations to advanced smart contract development and deployment.

🤖 MCP Server Tool Categories

• Basic Tools (4 tools): Echo, calculations, time, testnet funding
• Core Algorand Tools (8 tools): Account generation, payments, assets, transactions
• Swap Tools (5 tools): NEW! Asset swapping with Pera Swap integration
• Utility Tools (10 tools): Address validation, encoding, TEAL compilation, cryptography
• API Integration Tools (12 tools): Algod, Indexer, and NFD API access
• Advanced Transaction Tools (8 tools): Atomic groups, smart contracts, key registration
• ARC-26 Tools (2 tools): URI generation and QR codes
• Knowledge Tools (4 tools): Semantic search through Algorand documentation
• Wallet Management (2 tools): Secure wallet storage and retrieval

Total: 55+ tools for comprehensive Algorand development

⚡ Raycast Extension Features

• 🔐 Wallet Management: Secure wallet creation and management
• 💸 Transactions: Send ALGO and transfer assets with ease
• 🔄 Asset Swapping: NEW! DEX aggregation with real-time quotes
• 🪙 Asset Operations: Create and manage ASAs (tokens)
• 📊 Portfolio View: Detailed asset holdings and balances
• ⚡ Quick Actions: Keyboard shortcuts for all operations
• 🔗 Explorer Integration: Direct links to AlgoExplorer

Architecture

Security Features

Mnemonic Phrase Protection

• Encryption: Built-in AES-256-GCM encryption for mnemonic phrases
• Secure Storage: Methods for encrypting/decrypting wallet credentials
• Memory Safety: Sensitive data is handled securely and not logged

Network Configuration

• Testnet Default: Safely defaults to Algorand testnet
• Environment-based: Network configuration through environment variables
• Production Ready: Supports mainnet for production use

Prerequisites

• Node.js 18+
• npm or yarn
• TypeScript
• Algorand testnet account (for testing)

🛠️ Installation

MCP Server Setup

1. Clone or download this project

2. Install dependencies:

   bash

   npm install
   

3. Create environment configuration:

   bash

   # Create .env file with the following variables:
   ALGORAND_NETWORK=testnet
   ALGORAND_TOKEN=your_api_token
   ALGORAND_ALGOD=https://testnet-api.algonode.cloud
   ALGORAND_INDEXER=https://testnet-idx.algonode.cloud
   NFD_API_URL=https://api.nf.domains
   
   # Optional: For semantic search features
   QDRANT_URL=your_qdrant_url
   QDRANT_API_KEY=your_qdrant_api_key
   OPENAI_API_KEY=your_openai_api_key
   

4. Build the project:

   bash

   npm run build
   

Raycast Extension Setup

1. Navigate to the extension:
   bash

   cd raycast/algorand
   npm install
   npm run build
   

2. Import into Raycast:
   • Open Raycast → Extensions → Import Extension
   • Select the raycast/algorand folder
   • Start using Algorand commands from your toolbar!

📖 Detailed setup guides: See Raycast README for complete instructions.

Usage

Running the Server

# Start the MCP server
npm start

To expose the Streamable HTTP transport (required for Smithery or any remote deployment), use:

# Build and start the HTTP server locally
npm run build
npm run start:http

Development Mode

For development with automatic rebuilding:

# Build and run in development mode
npm run dev

Testing

# Test the server functionality
npm test

For manual testing of individual tools, see:

• TEST_QUERIES.md - Markdown format with detailed descriptions
• TEST_QUERIES.txt - Plain text format for easy copy-paste

Both files contain comprehensive test queries for all 47+ tools.

Deploying on Smithery

Smithery expects MCP servers to expose the Streamable HTTP transport and listen on the PORT environment variable (defaults to 8081). This repository now includes everything required for a custom-container deployment:

1. npm run build – compile the TypeScript project.
2. docker build -t algorand-mcp . – build the container defined in the provided Dockerfile.
3. docker run -p 8081:8081 --env-file .env algorand-mcp – test locally; ensure all MCP-related env vars are available.
4. Commit Dockerfile + smithery.yaml, then connect the repo inside Smithery and trigger a deployment. The platform automatically runs the container, sets PORT=8081, and hits /mcp over Streamable HTTP. Reference

The smithery.yaml file advertises the required configuration (Algorand endpoints, API keys, etc.) so that sessions launched from Smithery can inject the right secrets. For advanced tips—like enabling optional session configuration fields, handling /mcp CORS headers, and troubleshooting build failures—see the Smithery custom-container documentation. Reference

MCP Client Configuration

For VSCode with MCP Extension

Add to your VSCode settings:

{
  "mcpServers": {
    "algorand-mcp-server": {
      "command": "node",
      "args": ["path/to/your/project/dist/index.js"]
    }
  }
}

For Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "algorand-mcp-server": {
      "command": "node",
      "args": ["path/to/your/project/dist/index.js"]
    }
  }
}

For Cursor IDE

Add to your Cursor settings (Cursor > Preferences > Features > Model Context Protocol):

{
  "mcpServers": {
    "algorand-mcp-server": {
      "command": "node",
      "args": ["path/to/your/project/dist/index.js"],
      "env": {
        "ALGORAND_NETWORK": "testnet",
        "ALGORAND_TOKEN": "your_api_token",
        "ALGORAND_ALGOD": "https://testnet-api.algonode.cloud",
        "ALGORAND_INDEXER": "https://testnet-idx.algonode.cloud",
        "NFD_API_URL": "https://api.nf.domains"
      }
    }
  }
}

Note: Replace path/to/your/project/dist/index.js with the actual path to your compiled server file.

Cursor IDE Usage Tips

1. Environment Variables: The env section in the Cursor configuration allows you to set environment variables directly in the MCP server configuration.

2. Restart Required: After updating the MCP configuration in Cursor, restart the application for changes to take effect.

3. Debugging: Use the Cursor developer tools to monitor MCP server communication and troubleshoot any issues.

4. Tool Discovery: Once configured, you can access all 47+ Algorand tools directly through Cursor's AI assistant interface.

For VS Code Debugging

The project includes a .vscode/mcp.json configuration file for debugging within VS Code. You can use this with the MCP extension for VS Code.

Available Tools

Basic Tools (4 tools)

• echo: Echo back the provided message
• calculate: Perform basic mathematical calculations
• get_current_time: Get the current time in a specified timezone
• fund_testnet: Fund an Algorand testnet account using the official faucet

Core Algorand Tools (8 tools)

• generate_algorand_account: Generate a new Algorand account with address and mnemonic
• get_account_info: Get account information including balance and assets
• send_payment: Send Algo payment transaction (WARNING: Requires mnemonic phrase)
• create_asset: Create a new Algorand Standard Asset (ASA)
• opt_in_to_asset: Opt into an Algorand Standard Asset
• transfer_asset: Transfer an Algorand Standard Asset
• get_asset_info: Get information about an Algorand Standard Asset
• get_transaction: Get transaction details by transaction ID

Wallet Management (2 tools)

• store_wallet: Securely store a wallet with encrypted mnemonic
• load_wallet: Load a stored wallet and return the address

Utility Tools (10 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
• verify_bytes: Verify a signature against bytes with an Algorand address
• sign_bytes: Sign bytes with a secret key
• compile_teal: Compile TEAL source code to bytecode
• disassemble_teal: Disassemble TEAL bytecode into source code
• encode_obj: Encode an object to msgpack format
• decode_obj: Decode msgpack bytes to an object

API Integration Tools (12 tools)

Algod API (5 tools)

• algod_get_account_info: Get current account balance, assets, and auth address from algod
• algod_get_transaction_info: Get transaction details by transaction ID from algod
• algod_get_asset_info: Get asset details from algod
• algod_get_application_info: Get application details from algod
• algod_get_pending_transactions: Get pending transactions from algod mempool

Indexer API (5 tools)

• indexer_lookup_account_by_id: Get account information from indexer
• indexer_lookup_asset_by_id: Get asset information from indexer
• indexer_lookup_transaction_by_id: Get transaction details from indexer
• indexer_search_for_accounts: Search for accounts with various criteria
• indexer_search_for_transactions: Search for transactions with various criteria

NFD API (3 tools)

• nfd_get_nfd: Get NFD domain information by name
• nfd_get_nfds_for_address: Get all NFD domains owned by an address
• nfd_search_nfds: Search for NFD domains

Advanced Transaction Tools (8 tools)

• 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
• create_application: Create a new smart contract application on Algorand
• call_application: Call a smart contract application on Algorand
• optin_application: Opt-in to an Algorand application
• closeout_application: Close out from an Algorand application
• create_key_registration_transaction: Create a key registration transaction for participation
• freeze_asset: Freeze or unfreeze an asset for an account

ARC-26 Tools (2 tools)

• generate_algorand_uri: Generate a URI following the Algorand ARC-26 specification
• generate_algorand_qrcode: Generate a URI and QRCode following the Algorand ARC-26 specification

Knowledge Tools (1 tool)

• search_algorand_docs: Semantic search through Algorand documentation using AI embeddings

Project Structure

├── src/
│   ├── index.ts                    # Main server implementation
│   ├── algorand.ts                 # Core Algorand blockchain operations
│   ├── utilityTools.ts             # Address validation, encoding, TEAL compilation
│   ├── apiTools.ts                 # Algod, Indexer, and NFD API integration
│   ├── advancedTransactionTools.ts # Atomic groups, smart contracts, key registration
│   ├── arc26Tools.ts              # ARC-26 URI generation and QR codes
│   └── knowledgeTools.ts           # Semantic search and documentation access
├── dist/                          # Compiled JavaScript output
├── .vscode/
│   └── mcp.json                   # VS Code MCP configuration
├── .github/
│   └── copilot-instructions.md    # GitHub Copilot instructions
├── package.json                   # Node.js package configuration (v3.0.0)
├── tsconfig.json                  # TypeScript configuration
├── ENHANCED_FEATURES.md           # Detailed feature documentation
├── MCP_SETUP.md                   # MCP server setup instructions
├── TESTING.md                     # Testing guidelines
├── TEST_QUERIES.md                # Manual testing queries for all tools (markdown)
├── TEST_QUERIES.txt               # Manual testing queries for all tools (plain text)
└── README.md                      # This file

Development Guide

Modular Architecture

The server is organized into modular tool categories:

• algorand.ts: Core blockchain operations (accounts, payments, assets)
• utilityTools.ts: Address validation, encoding, TEAL compilation
• apiTools.ts: Algod, Indexer, and NFD API integration
• advancedTransactionTools.ts: Atomic groups, smart contracts, key registration
• arc26Tools.ts: ARC-26 URI generation and QR codes
• knowledgeTools.ts: Semantic search and documentation access

Adding New Tools

1. Choose the appropriate module for your tool category
2. Define the tool schema in the module's tools array
3. Create a Zod schema for input validation
4. Implement the service method in the corresponding service class
5. Add the tool handler in index.ts
6. Update the module exports to include the new tool

Example Tool Implementation

// In utilityTools.ts
export const MyTool = {
  name: 'my_tool',
  description: 'Description of what the tool does',
  inputSchema: {
    type: 'object' as const,
    properties: {
      input: {
        type: 'string',
        description: 'Input parameter description',
      },
    },
    required: ['input'],
  },
};

// Add to UtilityTools array
export const UtilityTools = [
  // ... existing tools
  MyTool,
];

// In utilityTools.ts service class
async myToolMethod(input: string): Promise<{ result: string }> {
  // Implement tool logic here
  return { result: `Processed: ${input}` };
}

// In index.ts
case 'my_tool': {
  const parsed = z.object({ input: z.string() }).parse(args);
  const result = await utilityService.myToolMethod(parsed.input);
  return {
    content: [
      {
        type: 'text',
        text: `Result: ${result.result}`,
      },
    ],
  };
}

🆕 What's New in v3.0

🔄 Swap Functionality

• DEX Aggregation: Powered by Pera Swap SDK for best prices
• Multi-DEX Support: Tinyman, Vestige, and more DEXs
• Real-time Quotes: Live pricing with slippage control
• Secure Execution: Client-side transaction signing
• 5 New MCP Tools: Complete swap workflow integration

⚡ Raycast Extension

• Native macOS Integration: Access Algorand from your toolbar
• Beautiful UI: Native Raycast components with rich formatting
• Keyboard Shortcuts: Quick actions for power users
• Secure Storage: Encrypted wallet management
• Portfolio View: Detailed asset holdings and balances

🛠️ Enhanced Developer Experience

• TypeScript Support: Full type safety across all tools
• Better Error Handling: More descriptive error messages
• Documentation Search: Semantic search through Algorand docs
• Asset Discovery: Search and explore available tokens

Security Considerations

• Input Validation: All tools use Zod schemas for robust input validation
• Mnemonic Protection: Built-in AES-256-GCM encryption for wallet storage
• Network Safety: Defaults to testnet for safe development
• Error Handling: Comprehensive error handling prevents sensitive data leakage
• Memory Safety: Sensitive data is handled securely and not logged
• Production Ready: Supports mainnet with proper environment configuration

Security Best Practices

• Never commit mnemonic phrases or private keys to version control
• Use environment variables for sensitive configuration
• Test thoroughly on testnet before mainnet deployment
• Implement proper access controls in production
• Monitor for unusual activity and implement rate limiting

Contributing

1. Fork the repository
2. Create a feature branch
3. Implement your changes with proper tests
4. Submit a pull request

License

ISC License - see package.json for details

Key Features

🔐 Security First

• AES-256-GCM encryption for wallet storage
• Comprehensive input validation with Zod schemas
• Testnet-first approach for safe development
• Production-ready mainnet support

🚀 Comprehensive Tool Suite

• 47+ tools covering all aspects of Algorand development
• Modular architecture for easy maintenance and extension
• Real-time blockchain interaction capabilities
• Advanced smart contract deployment and management

🔗 Full API Integration

• Direct Algod API access for real-time data
• Indexer API for advanced search and analytics
• NFD (Name Service) integration for human-readable addresses
• Semantic search through Algorand documentation

🛠️ Developer Experience

• TypeScript for type safety and better development experience
• Comprehensive error handling and logging
• Easy-to-use MCP client configuration
• Extensive documentation and examples

📱 Modern Standards

• ARC-26 compliant URI generation
• QR code generation for mobile wallet integration
• Atomic transaction groups for complex operations
• Smart contract deployment and interaction

Resources

• Model Context Protocol Documentation
• MCP SDK Reference
• Algorand Developer Portal
• Algorand SDK Documentation
• ARC-26 Specification