FLock-io/etherscan-mcp-python

Etherscan MCP Python Server

A complete Python implementation of the Etherscan Model Context Protocol (MCP) server, providing comprehensive access to Ethereum blockchain data through the Etherscan API.

Overview

This server provides 53+ tools for accessing Ethereum blockchain data, including:

• Account Tools: Balance checking, transaction history, internal transactions
• Block Tools: Block data, rewards, timing information
• Contract Tools: Source code, ABI, verification status
• Transaction Tools: Transaction details, receipts, status
• Token Tools: Transfers, balances, supply information
• Gas Tools: Gas prices, estimates, oracle data
• Statistics Tools: Network metrics, supply data
• RPC Tools: Ethereum RPC proxy methods
• Logs Tools: Event logs and filtering

Requirements

• Python 3.8+
• Etherscan API Key

Installation

cd etherscan-mcp-python
pip install -e .

Configuration

Set your Etherscan API key as an environment variable:

export ETHERSCAN_API_KEY="your_api_key_here"

Usage

Standalone Server

python server.py

With MCP Tools (Agno Framework)

from agno.tools.mcp import MCPTools

etherscan_mcp = MCPTools(
    command="python etherscan-mcp-python/server.py",
    env={"ETHERSCAN_API_KEY": "your_api_key"},
    timeout_seconds=120
)

Complete Tool Reference

🏦 Account Tools (12 tools)

🧱 Block Tools (4 tools)

📄 Contract Tools (4 tools)

🔄 Transaction Tools (2 tools)

🪙 Token Tools (2 tools)

⛽ Gas Tools (3 tools)

📊 Statistics Tools (13 tools)

📝 Logs Tools (3 tools)

🔗 RPC Proxy Tools (13 tools)

🎯 Use Cases & Examples

Basic Balance Check

# Get ETH balance for single address
account_balance(address="0x...", chainid="1")

# Get balances for multiple addresses (up to 20)
account_balancemulti(address="0x...,0x...,0x...", chainid="1")

Transaction Analysis

# Get transaction history for address
account_txlist(address="0x...", startblock="0", endblock="99999999")

# Get internal transactions (contract interactions)
account_txlistinternal(address="0x...", page="1", offset="100")

Block Information

# Get transaction count in specific block (like the web3_GAIA_test.py example)
block_getblocktxnscount(blockno="17000000", chainid="1")

# Get block mining rewards
block_getblockreward(blockno="17000000", chainid="1")

Market Data

# Get current ETH price
stats_ethprice(chainid="1")

# Get current gas prices
gas_gasoracle(chainid="1")

Smart Contract Analysis

# Get contract source code (if verified)
contract_getsourcecode(address="0x...", chainid="1")

# Get contract ABI
contract_getabi(address="0x...", chainid="1")

🔧 Advanced Configuration

Multi-Chain Support

The server supports multiple Ethereum networks via the chainid parameter:

• "1" - Ethereum Mainnet (default)
• "5" - Goerli Testnet
• "11155111" - Sepolia Testnet
• And other supported networks

Error Handling

The server includes comprehensive error handling for:

• ❌ Missing API keys
• ❌ Invalid parameters
• ❌ API rate limits
• ❌ Network timeouts
• ❌ Malformed responses

Performance Optimization

• ✅ Synchronous HTTP client for MCP compatibility
• ✅ Efficient JSON parsing and response formatting
• ✅ Proper timeout handling (120 seconds default)
• ✅ Memory-efficient tool registration

🔐 Security & Best Practices

API Key Management

• Store ETHERSCAN_API_KEY in environment variables
• Never commit API keys to version control
• Use .env files for local development
• Rotate API keys regularly

Rate Limiting

• Etherscan API has rate limits (free tier: 5 calls/sec)
• The server respects these limits
• Consider upgrading to Etherscan Pro for higher limits

Data Validation

• All input parameters are validated
• API responses are checked for errors
• Malformed data is handled gracefully

🆘 Troubleshooting

Common Issues

❌ "ETHERSCAN_API_KEY not set"

• Solution: Set the environment variable export ETHERSCAN_API_KEY="your_key"

❌ "Connection closed" or "Runtime error"

• Solution: Ensure you're not running in nested async context
• Check that the server.py uses synchronous main() function

❌ "Tool not found"

• Solution: Verify tool names use underscores (account_balance not account/balance)
• Check that tool renaming for Gemini compatibility is applied

❌ "Timeout after 120 seconds"

• Solution: Check internet connectivity and API key validity
• Verify Etherscan API is not experiencing outages

Debug Mode

For debugging, you can modify the server to add verbose logging:

import logging
logging.basicConfig(level=logging.DEBUG)

🤝 Contributing

Adding New Tools

1. Choose appropriate tool category file (src/tools/)
2. Follow existing patterns for parameter validation
3. Add comprehensive docstrings
4. Test with actual API calls
5. Update this README with new tool documentation