Which integrations are available for this server?

Provides tools for accessing Ethereum blockchain data including account balances, transactions, blocks, contracts, tokens, gas, logs, and statistics via the Etherscan API.

How do I use Etherscan MCP Python?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Etherscan MCP Python What's the ETH balance of 0x742d35Cc6634C0532925a3b844Bc4e6f3aC1b2D7?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Etherscan MCP Python

by FLock-io

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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

Related MCP server: MCP Etherscan Server

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

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Etherscan A
io.etherscan
Read-only Etherscan V2 blockchain data: balances, transactions, transfers, tokens, contracts, logs.
Blockchain Cryptocurrency Web3 & Decentralized Tech
1
etherscan-api-mcp C
io.github.junct-bot
Etherscan Api - 71 tools for data, metrics, and on-chain analytics
Blockchain Web3 & Decentralized Tech Cryptocurrency
2
Etherscan A
io.github.pipeworx-io
Etherscan MCP — multichain block-explorer API (Etherscan V2)
Blockchain Web3 & Decentralized Tech Cryptocurrency
3
demomagic-duckchain-mcp
ai.smithery
Explore blockchain data across addresses, tokens, blocks, and transactions. Investigate any transa…
Blockchain Web3 & Decentralized Tech Cryptocurrency
2

Related MCP Servers

MCP Etherscan Server
Blockchain Web3 & Decentralized Tech
crazyrabbitLTC
A
license
A
quality
D
maintenance
Facilitates interaction with Ethereum blockchain data via Etherscan's API, providing real-time access to balances, transactions, token transfers, contract ABIs, gas prices, and ENS name resolutions.
Updated 2 years ago (2024-12-31 17:34 UTC)
6
7 npm
30
MIT
MCP Etherscan Server
Blockchain Web3 & Decentralized Tech
5ajaki
A
license
A
quality
D
maintenance
Provides Ethereum blockchain data tools via Etherscan's API, enabling users to check ETH balances, view transactions, track token transfers, fetch contract ABIs, monitor gas prices, and resolve ENS names.
Updated 2 years ago (2025-01-23 06:00 UTC)
6
7 npm
1
MIT
DuckChain MCP Server
Blockchain Web3 & Decentralized Tech
demomagic
F
license
Not graded
quality
D
maintenance
Enables comprehensive blockchain data analysis and exploration through the BlockScout API. Provides 56+ tools for transaction analysis, address exploration, token management, smart contract analysis, and market research across multiple blockchain networks.
Updated a year ago (2025-09-14 04:54 UTC)
-
MCP Etherscan Server
Blockchain Web3 & Decentralized Tech Cryptocurrency
ThirdGuard
A
license
A
quality
D
maintenance
Provides Ethereum blockchain data tools via Etherscan's API, enabling users to check balances, view transactions, track token transfers, fetch contract ABIs and code, monitor gas prices, and resolve ENS names.
Updated a year ago (2025-08-29 09:05 UTC)
7
MIT

Etherscan MCP Python Server

Overview

Requirements

Installation

Configuration

Usage

Standalone Server

With MCP Tools (Agno Framework)

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

Transaction Analysis

Block Information

Market Data

Smart Contract Analysis

🔧 Advanced Configuration

Multi-Chain Support

Error Handling

Performance Optimization

🔐 Security & Best Practices

API Key Management

Rate Limiting

Data Validation

🆘 Troubleshooting

Common Issues

Debug Mode

🤝 Contributing

Adding New Tools

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

MCP Etherscan Server

MCP Etherscan Server

DuckChain MCP Server

MCP Etherscan Server