<p align="center"> <img src="resources/logo-full.svg" alt="FLock Logo" width="400" /> </p>

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)

Tool Name	Description	Key Parameters
account_balance	Get ETH balance for single address	address, chainid
account_balancemulti	Get ETH balance for multiple addresses (up to 20)	address (comma-separated), chainid
account_txlist	Get normal transactions by address	address, startblock, endblock, page, offset
account_txlistinternal	Get internal transactions by address	address, startblock, endblock, page, offset
account_txlistinternal_byhash	Get internal transactions by transaction hash	txhash, chainid
account_txlistinternal_byblock	Get internal transactions by block range	startblock, endblock, page, offset
account_tokentx	Get ERC20 token transfer events	address, contractaddress, startblock, endblock
account_tokennfttx	Get ERC721 (NFT) token transfer events	address, contractaddress, startblock, endblock
account_token1155tx	Get ERC1155 token transfer events	address, contractaddress, startblock, endblock
account_fundedby	Get address funding source and age	address, chainid
account_getminedblocks	Get blocks validated by address	address, blocktype, page, offset
account_txsBeaconWithdrawal	Get beacon chain withdrawals	address, startblock, endblock, page, offset

🧱 Block Tools (4 tools)

Tool Name	Description	Key Parameters
block_getblockreward	Get block mining reward and uncle rewards	blockno, chainid
block_getblockcountdown	Get estimated time until block is mined	blockno, chainid
block_getblocknobytime	Get block number by timestamp	timestamp, closest, chainid
block_getblocktxnscount	Get number of transactions in block	blockno, chainid

📄 Contract Tools (4 tools)

Tool Name	Description	Key Parameters
contract_getabi	Get contract ABI for verified contracts	address, chainid
contract_getsourcecode	Get verified contract source code	address, chainid
contract_getcontractcreation	Get contract creator and creation tx hash	contractaddresses, chainid
contract_checkverifystatus	Check contract verification status	guid, chainid

🔄 Transaction Tools (2 tools)

Tool Name	Description	Key Parameters
transaction_getstatus	Get contract execution status	txhash, chainid
transaction_gettxreceiptstatus	Get transaction receipt status	txhash, chainid

🪙 Token Tools (2 tools)

Tool Name	Description	Key Parameters
stats_tokensupply	Get ERC20 token total supply	contractaddress, chainid
account_tokenbalance	Get ERC20 token balance of address	contractaddress, address, chainid

⛽ Gas Tools (3 tools)

Tool Name	Description	Key Parameters
gas_gasestimate	Get estimated confirmation time for gas price	gasprice, chainid
gas_gasoracle	Get current safe/proposed/fast gas prices	chainid
stats_dailyavggaslimit	Get historical daily average gas limit	startdate, enddate, sort, chainid

📊 Statistics Tools (13 tools)

Tool Name	Description	Key Parameters
stats_ethsupply	Get total ETH supply (excluding staking/burnt)	chainid
stats_ethsupply2	Get total ETH supply (including staking/burnt)	chainid
stats_ethprice	Get current ETH price	chainid
stats_chainsize	Get blockchain size over date range	startdate, enddate, clienttype, syncmode
stats_nodecount	Get total discoverable nodes	chainid
stats_dailytxnfee	Get daily transaction fees paid to miners	startdate, enddate, sort
stats_dailynewaddress	Get daily new address count	startdate, enddate, sort
stats_dailynetutilization	Get daily network utilization percentage	startdate, enddate, sort
stats_dailyavghashrate	Get daily average network hash rate	startdate, enddate, sort
stats_dailytx	Get daily transaction count	startdate, enddate, sort
stats_dailyavgnetdifficulty	Get daily average mining difficulty	startdate, enddate, sort
stats_ethdailyprice	Get historical ETH prices	startdate, enddate, sort

📝 Logs Tools (3 tools)

Tool Name	Description	Key Parameters
logs_getLogsByAddress	Get event logs from address with block range	address, fromBlock, toBlock, page, offset
logs_getLogsByTopics	Get event logs filtered by topics	fromBlock, toBlock, topic0-3, operators
logs_getLogsByAddressAndTopics	Get event logs from address filtered by topics	address, fromBlock, toBlock, topic0-3

🔗 RPC Proxy Tools (13 tools)

Tool Name	Description	Key Parameters
proxy_eth_blockNumber	Get latest block number	chainid
proxy_eth_getBlockByNumber	Get block information by number	tag, boolean, chainid
proxy_eth_getUncleByBlockNumberAndIndex	Get uncle block by number and index	tag, index, chainid
proxy_eth_getBlockTransactionCountByNumber	Get transaction count in block	tag, chainid
proxy_eth_getTransactionByHash	Get transaction by hash	txhash, chainid
proxy_eth_getTransactionByBlockNumberAndIndex	Get transaction by block and index	tag, index, chainid
proxy_eth_getTransactionCount	Get transaction count by address	address, tag, chainid
proxy_eth_getTransactionReceipt	Get transaction receipt	txhash, chainid
proxy_eth_call	Execute message call without transaction	to, data, tag, chainid
proxy_eth_getCode	Get code at address	address, tag, chainid
proxy_eth_getStorageAt	Get storage value at position	address, position, tag, chainid
proxy_eth_gasPrice	Get current gas price	chainid
proxy_eth_estimateGas	Estimate gas for transaction	data, to, value, gas, gasPrice

🎯 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