{
  "markdown": "# Etherscan MCP Server\n\n> An MCP server for [Etherscan](https://etherscan.io) — connect any MCP-compatible client to the Ethereum blockchain explorer.\n\n[![npm version](https://img.shields.io/npm/v/@supernova123/etherscan-mcp-server)](https://www.npmjs.com/package/@supernova123/etherscan-mcp-server)\n[![npm downloads](https://img.shields.io/npm/dm/@supernova123/etherscan-mcp-server)](https://www.npmjs.com/package/@supernova123/etherscan-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blueviolet)](https://modelcontextprotocol.io)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue)](https://www.typescriptlang.org/)\n[![Claude Desktop](https://img.shields.io/badge/Claude%20Desktop-ready-orange)](https://claude.ai/download)\n[![Cursor](https://img.shields.io/badge/Cursor-compatible-blue)](https://cursor.sh)\n\n## What is this?\n\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI assistants and agents access to Etherscan's Ethereum blockchain explorer API — ETH balances, ERC-20 token balances, transaction history, contract ABIs, and gas prices — through natural language.\n\nUse it with **Claude Desktop**, **Cursor**, **Windsurf**, **Cline**, **Continue**, or any MCP-compatible client to inspect wallets, audit contracts, and analyze on-chain activity.\n\n## Why use this?\n\n- **No API key required** — works out of the box with Etherscan's free tier (limited to ~1 call/5s without a key)\n- **Optional API key support** — set `ETHERSCAN_API_KEY` for 5 calls/sec and full results\n- **8 built-in tools** — covers the most common on-chain queries\n- **Clean markdown output** — results read naturally in chat\n- **Rate-limited automatically** — respects free tier limits, retries on 429\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_eth_balance` | Get native ETH balance for an address |\n| `get_token_balances` | Get all ERC-20 token balances for an address |\n| `get_transaction` | Get full details for a transaction by hash |\n| `get_transactions_by_address` | Get normal (external) transactions for an address |\n| `get_erc20_transfers` | Get ERC-20 token transfer events for an address |\n| `get_internal_transactions` | Get internal (contract-called) transactions for an address |\n| `get_contract_abi` | Get the ABI for a verified smart contract |\n| `get_gas_price` | Get current gas price oracle (slow/standard/fast in Gwei) |\n\n## Quick Start\n\n### 1. Add to your MCP client\n\nAdd this to your MCP client config (e.g. `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"etherscan\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"etherscan-mcp-server\"]\n    }\n  }\n}\n```\n\nThat's it. npx downloads and runs it automatically. For higher rate limits, get a free API key at [etherscan.io/apis](https://etherscan.io/apis) and add it:\n\n```json\n{\n  \"mcpServers\": {\n    \"etherscan\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"etherscan-mcp-server\"],\n      \"env\": {\n        \"ETHERSCAN_API_KEY\": \"your_key_here\"\n      }\n    }\n  }\n}\n```\n\n### 2. Use it\n\nAsk your AI assistant things like:\n\n- \"What's the ETH balance of vitalik.eth's address `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`?\"\n- \"Show me the ERC-20 token balances for that address\"\n- \"Get details for transaction `0x...`\"\n- \"List the last 20 normal transactions for this address\"\n- \"Show me all USDT transfers to this wallet\"\n- \"Fetch the ABI for the USDC contract `0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`\"\n- \"What are current gas prices on Ethereum mainnet?\"\n\n## Example Output\n\n### `get_eth_balance`\n\n```\nETH Balance for 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\n\n247.3821 ETH\n```\n\n### `get_gas_price`\n\n```\n⛽ Etherscan Gas Price Oracle\n\n- Safe Low (🐢): 12.50 Gwei\n- Standard (🚗): 15.20 Gwei\n- Fast (🚀): 18.90 Gwei\n\n- Last Block: 19850000\n- Gas Used Ratio: 0.512\n- Suggested Base Fee: 13.40 Gwei\n\n*Estimated tx cost for 21,000 gas: 🐢 0.000263 ETH | 🚀 0.000397 ETH*\n```\n\n### `get_transactions_by_address`\n\n```\nNormal Transactions for 0xd8dA...6045 (20 results, page 1)\n\n- ✅ ↗ OUT 0.5 ETH · transfer — block 19,850,123 — 2026-06-05 — gas: 15.20 Gwei — hash: 0x4f8a2b9c3d1e5f7a...\n- ✅ ↙ IN 1.2 ETH · transfer — block 19,849,876 — 2026-06-05 — gas: 14.80 Gwei — hash: 0x9c1d4e7f2a8b6c3d...\n- ❌ ↗ OUT 0.0 ETH · swapExactTokensForETH — block 19,849,500 — 2026-06-05 — gas: 22.10 Gwei — hash: 0x2b7c9e1f4a3d8b5c...\n```\n\n### `get_contract_abi`\n\n```\nContract ABI for 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\n\n- Functions: 28\n- Events: 13\n- Constructors: 1\n- Fallback/Receive: 0\n\n### Functions (showing first 25)\n  - `name()` → string (view)\n  - `symbol()` → string (view)\n  - `decimals()` → uint8 (view)\n  - `totalSupply()` → uint256 (view)\n  - `balanceOf(address)` → uint256 (view)\n  - `transfer(address,uint256)` → bool (nonpayable)\n  - `approve(address,uint256)` → bool (nonpayable)\n  - `transferFrom(address,address,uint256)` → bool (nonpayable)\n  ...\n```\n\n## Use Cases\n\n### Wallet Inspection\n\"Check the ETH and token balances of this address\" — get a snapshot of any wallet's holdings in seconds. Works with any Ethereum address, including smart contract wallets and multisigs.\n\n### Transaction Forensics\n\"Show me the last 20 transactions for this address\" — trace on-chain activity, identify counterparties, and understand fund flows. Use `get_internal_transactions` for contract calls and `get_erc20_transfers` for token movements.\n\n### Smart Contract Analysis\n\"Get the ABI for the Uniswap Router contract\" — fetch verified contract ABIs to understand what functions are available. Essential for debugging failed transactions or understanding how a protocol works.\n\n### Gas Optimization\n\"What are current gas prices?\" — get slow/standard/fast gas estimates with projected transaction costs. Time your transactions to save on fees.\n\n### DeFi Portfolio Tracking\n\"Show me all token balances for my wallet\" — aggregate holdings across ERC-20 tokens. Combine with `get_prices` from the CoinGecko MCP server for full portfolio valuation.\n\n### Security Auditing\n\"List all internal transactions for this contract\" — trace internal calls to understand contract behavior. Useful for identifying unusual patterns or verifying that a contract does what it claims.\n\n## Security\n\n- **No API key required** — works with Etherscan's free tier. Optional API key for higher rate limits.\n- **Read-only** — only fetches public blockchain data from Etherscan's API. No writes, no mutations.\n- **No local file access** — does not read or write any files on your machine.\n- **No shell access** — does not execute commands or spawn processes.\n- **Rate-limited** — automatically caps requests to stay within free tier limits.\n- **Open source** — MIT licensed. Inspect the code at [GitHub](https://github.com/friendlygeorge/etherscan-mcp-server).\n\n## Troubleshooting\n\n### \"API key required\" or very slow responses\nWithout an API key, Etherscan limits you to 1 call per 5 seconds. Get a free key at [etherscan.io/apis](https://etherscan.io/apis) and set the `ETHERSCAN_API_KEY` environment variable for 5 calls/sec.\n\n### \"Rate limit exceeded\" (429)\nThe server auto-retries on 429, but rapid queries can still hit limits. With a free API key, you get 5 calls/sec. Space requests ~200ms apart for best results.\n\n### \"Contract not found\" or empty ABI\nOnly verified contracts have ABIs on Etherscan. If a contract isn't verified, the API returns an error. Check the contract's verification status on etherscan.io first.\n\n### Server won't start\nMake sure Node.js 18+ is installed: `node --version`. If using npx, ensure npm is up to date: `npm install -g npm@latest`.\n\n### MCP client can't connect\nVerify the config path is correct. Claude Desktop uses `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS and `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows. Restart the client after config changes.\n\n### \"Address checksum\" errors\nEtherscan expects checksummed addresses (mixed case). The server handles this automatically, but if you see errors, try the checksummed version from etherscan.io.\n\n## Requirements\n\n- Node.js 18+\n- Etherscan API key (recommended) — get a free one at [etherscan.io/apis](https://etherscan.io/apis)\n\n## Rate Limits\n\nThe server automatically rate-limits requests to ~4 calls/second to stay within Etherscan's free tier (5 calls/sec). Without an API key, Etherscan limits you to 1 call/5 seconds.\n\nTo use a higher limit, sign up for a free Etherscan API key and set the `ETHERSCAN_API_KEY` environment variable:\n\n```json\n{\n  \"mcpServers\": {\n    \"etherscan\": {\n      \"command\": \"etherscan-mcp-server\",\n      \"env\": {\n        \"ETHERSCAN_API_KEY\": \"your_key_here\"\n      }\n    }\n  }\n}\n```\n\n## Development\n\n```bash\ngit clone https://github.com/nova/etherscan-mcp-server.git\ncd etherscan-mcp-server\nnpm install\nnpm run build\nnpm start\n```\n\n## License\n\nMIT\n",
  "bytes": 8921,
  "sha": "693a8916b89a45f0db2657983d9e0f6075af1ba9b2e2cf9bb6d3bb27319dfeb9",
  "repo_slug": "friendlygeorge/etherscan-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_friendlygeorge_etherscan_mcp_s_26b13051/readme"
}