{"id":50834345,"url":"https://github.com/friendlygeorge/etherscan-mcp-server","last_synced_at":"2026-06-14T02:11:12.082Z","repository":{"id":362904119,"uuid":"1260869545","full_name":"friendlygeorge/etherscan-mcp-server","owner":"friendlygeorge","description":"MCP server for Etherscan — Ethereum blockchain data, balances, transactions, contracts. Free tier available.","archived":false,"fork":false,"pushed_at":"2026-06-06T13:06:13.000Z","size":21,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T14:12:07.262Z","etag":null,"topics":["ai","ai-tools","api","blockchain","ethereum","etherscan","llm","mcp","model-context-protocol","typescript","web3"],"latest_commit_sha":null,"homepage":"https://github.com/friendlygeorge/etherscan-mcp-server#readme","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/friendlygeorge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["nova"]}},"created_at":"2026-06-06T01:02:12.000Z","updated_at":"2026-06-06T13:26:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/friendlygeorge/etherscan-mcp-server","commit_stats":null,"previous_names":["friendlygeorge/etherscan-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/friendlygeorge/etherscan-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fetherscan-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fetherscan-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fetherscan-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fetherscan-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/friendlygeorge","download_url":"https://codeload.github.com/friendlygeorge/etherscan-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/friendlygeorge%2Fetherscan-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34306817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-tools","api","blockchain","ethereum","etherscan","llm","mcp","model-context-protocol","typescript","web3"],"created_at":"2026-06-14T02:11:11.106Z","updated_at":"2026-06-14T02:11:12.074Z","avatar_url":"https://github.com/friendlygeorge.png","language":"JavaScript","funding_links":["https://github.com/sponsors/nova"],"categories":[],"sub_categories":[],"readme":"# Etherscan MCP Server\n\n\u003e 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriendlygeorge%2Fetherscan-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffriendlygeorge%2Fetherscan-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffriendlygeorge%2Fetherscan-mcp-server/lists"}