etherscanmcp
No description available
Ask AI about etherscanmcp
Powered by Claude ยท Grounded in docs
I know everything about etherscanmcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Etherscan MCP Server
A Model Context Protocol (MCP) server that integrates with the Etherscan API, providing access to Ethereum blockchain data through standardized MCP tools.
Features
This MCP server exposes all major Etherscan API endpoints as MCP tools, organized into the following categories:
โจ Multichain Support: All tools support Etherscan API V2's multichain functionality via the optional chainid parameter. Query data from Ethereum (1), BSC (56), Polygon (137), Base, Arbitrum, and 60+ other supported chains!
๐งฑ Accounts
get_balance- Get ETH balance for a single addressget_multiple_balances- Get ETH balances for multiple addressesget_transactions- Get list of normal transactions for an address
โ๏ธ Blocks
get_block_reward- Get block and uncle rewards by block numberget_block_countdown- Get estimated time until a block is minedget_block_number_by_timestamp- Get block number closest to a timestamp
๐ธ Transactions
get_tx_status- Get transaction execution statusget_internal_transactions- Get internal transactions by hash or address
๐ง Contracts
get_abi- Get contract ABI for verified contractsget_source_code- Get contract source code for verified contracts
โฝ Gas Tracker
get_gas_oracle- Get current gas prices (Safe, Propose, Fast)
๐ฐ Tokens
get_token_supply- Get total supply of an ERC-20 tokenget_token_balance- Get ERC-20 token balance for an address
๐งฎ Stats
get_eth_price- Get current ETH price in USD and BTCget_node_count- Get total number of Ethereum nodes
Prerequisites
- Node.js 18+
- npm or yarn
- Etherscan API key (Get one here)
Installation
For Local Development
-
Clone or download this repository
-
Install dependencies:
npm install
- Set your Etherscan API key as an environment variable:
# Windows (PowerShell)
$env:ETHERSCAN_API_KEY="your-api-key-here"
# Windows (CMD)
set ETHERSCAN_API_KEY=your-api-key-here
# Linux/Mac
export ETHERSCAN_API_KEY=your-api-key-here
For Smithery Deployment
When deploying to Smithery, users will be prompted to provide their own ETHERSCAN_API_KEY as an environment variable in the Smithery configuration. The server will automatically use the provided API key.
Building
Compile TypeScript to JavaScript:
npm run build
Usage
Running the Server
The server uses stdio transport and should be configured in your MCP client:
npm start
MCP Client Configuration
Add this server to your MCP client configuration (e.g., in Claude Desktop's claude_desktop_config.json):
{
"mcpServers": {
"etherscan-mcp": {
"command": "node",
"args": ["path/to/etherscan-mcp/dist/index.js"],
"env": {
"ETHERSCAN_API_KEY": "your-api-key-here"
}
}
}
}
Important: Always provide your own Etherscan API key. Never commit API keys to version control.
Example Tool Usage
Once connected to an MCP client, you can use tools like:
- Get balance:
get_balancewithaddress: "0x..." - Get transactions:
get_transactionswithaddress: "0x..."and optional pagination - Get gas prices:
get_gas_oracle(no parameters needed) - Get token balance:
get_token_balancewithcontractaddressandaddress
Multichain Usage
All tools support the optional chainid parameter for multichain queries:
- Ethereum Mainnet:
chainid: 1(default if omitted) - BNB Smart Chain:
chainid: 56 - Polygon:
chainid: 137 - Base:
chainid: 8453 - Arbitrum:
chainid: 42161
Example: Query BSC balance with get_balance({ address: "0x...", chainid: 56 })
See the Etherscan API documentation for the full list of supported chains.
Development
Project Structure
.
โโโ src/
โ โโโ index.ts # Main server implementation
โโโ dist/ # Compiled JavaScript (generated)
โโโ package.json
โโโ tsconfig.json
โโโ README.md
Scripts
npm run build- Compile TypeScriptnpm start- Run the compiled servernpm run dev- Build and run in one command
API Rate Limits
Etherscan API has rate limits based on your API key tier:
- Free tier: 5 calls/second
- Standard tier: 10 calls/second
- Advanced tier: 15 calls/second
The server will return errors if rate limits are exceeded.
Error Handling
The server validates all required parameters and returns appropriate MCP errors:
InvalidParams- Missing or invalid parametersMethodNotFound- Unknown tool nameInternalError- API call failures or other errors
License
MIT
