0xGval/evm-python-mcp

Onchain MCP Server

A comprehensive Model Context Protocol (MCP) server that provides tools for querying onchain data across multiple blockchain networks. This server supports 12+ blockchain networks and provides tools for ETH balances, ERC20 token balances, NFT balances, transaction analysis, and contract auditing.

Features

🔗 Multi-Chain Support

• Ethereum (Mainnet, Sepolia)
• Polygon
• Arbitrum
• Optimism
• BSC (Binance Smart Chain)
• Avalanche
• Base
• Scroll
• Blast
• Hyperliquid
• Plasma

🛠️ Available Tools

1. ETH Balance Tool - Get native token balances
2. ERC20 Balance Tool - Token balance queries
3. NFT Balance Tool - ERC721/ERC1155 NFT balances
4. Transaction Fetcher - Detailed transaction analysis with ERC-20 transfer detection
5. Logs Query Tool - Event log analysis
6. Token Metadata Tool - Token information and metadata
7. Contract Audit Tool - Comprehensive contract analysis and security auditing

📋 Available Prompts

1. Contract Security Audit - AI-powered security analysis
2. Quick Analysis - Fast contract overview
3. Deep Dive Analysis - Comprehensive contract examination

Installation

1. Clone the repository

   git clone https://github.com/0xGval/onchain-mcp.git
   cd onchain-mcp
   

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Configure API keys

   cp config_example.py config.py
   # Edit config.py with your API keys
   

Configuration

Required API Keys

• Alchemy API Key - For RPC endpoints
• Etherscan API Key - For contract verification and source code

Environment Variables

Set your API keys as environment variables:

export ETHERSCAN_API_KEY="your_etherscan_api_key"

Or add them directly to config.py:

"etherscan_api_key": "your_etherscan_api_key"

Usage

Running the Server

python server.py

Using with Claude Desktop

To use this MCP server with Claude Desktop, you need to configure it in your Claude Desktop settings:

1. Open Claude Desktop Settings
2. Go to "Developers" tab
3. Add a new MCP server with these settings:

{
  "mcpServers": {
    "onchain-mcp": {
      "command": "python",
      "args": ["path/to/your/onchain-mcp/server.py"],
      "env": {
        "ETHERSCAN_API_KEY": "your_etherscan_api_key"
      }
    }
  }
}

4. Replace the path with your actual server.py location
5. Add your API keys to the environment variables
6. Restart Claude Desktop

Using with Other MCP Clients

The server provides tools that can be used with MCP-compatible clients like Cursor, or other MCP clients. The server exposes these tools via the MCP protocol.

How to Use the Tools with Claude

Once configured, you can use the tools directly in your conversations with Claude:

Example Prompts:

• "Get the ETH balance for address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
• "Check the USDC balance for this address: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
• "Analyze this transaction: 0xe3769f745ff477de5853b7410e62d8c0c32ae4f87982928432562dfabe6440eb"
• "Audit this contract: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
• "Get the metadata for this token: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

Available Commands:

• eth_balance_tool - Check ETH balances
• erc20_balance_tool - Check token balances
• nft_balance_tool - Check NFT holdings
• tx_get_tool - Analyze transactions
• contract_audit_tool - Audit smart contracts
• token_metadata_tool - Get token information
• logs_tool - Query blockchain events

Troubleshooting Claude Desktop

Common Issues:

1. Server not starting: Make sure Python is in your PATH and all dependencies are installed
2. API key errors: Verify your API keys are correct and have sufficient quota
3. Network errors: Check your internet connection and RPC endpoint availability
4. Permission errors: Ensure Claude Desktop has permission to run Python scripts

Debug Steps:

1. Test the server manually: python server.py
2. Check Claude Desktop logs for error messages
3. Verify the server path in your MCP configuration
4. Ensure all environment variables are set correctly

API Documentation

Tools

Prompts

Examples

Get ETH Balance

result = eth_balance_tool("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "mainnet")

Get ERC20 Balance

result = erc20_balance_tool(
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", 
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", 
    "mainnet"
)

Analyze Transaction

result = tx_get_tool("0xe3769f745ff477de5853b7410e62d8c0c32ae4f87982928432562dfabe6440eb", "mainnet")

Contract Audit

result = contract_audit_tool("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "mainnet", "audit")

Network Support

The server supports multiple blockchain networks with different capabilities:

• Full Support: Ethereum, Polygon, Arbitrum, Optimism, BSC, Avalanche, Base, Scroll, Blast
• Limited Support: Solana, Plasma (basic functionality)

Security

• API keys are stored in environment variables
• Rate limiting is implemented to prevent abuse
• Input validation for all parameters
• Error handling for network failures

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

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

Support

For issues and questions, please open an issue on GitHub.