dericsanandres/MCP-Server-Ether-Scanner

MCP Blockchain Scanner

Multi-chain MCP server for whale detection and blockchain analysis. Works with Claude Code, Claude Desktop, GPT Codex, and any MCP-compatible client.

Supported Chains

Expansion-Ready

The architecture supports adding any EVM chain. These are pre-configured but commented out in src/core/chains.py:

To enable, uncomment the chain config in chains.py and add the API key to .env.

Quick Start

# 1. Setup
make setup
cp .env.example .env
# Edit .env with your API keys

# 2. Configure MCP client
make config-claude   # For Claude Desktop
make config-codex    # For GPT Codex

# 3. Restart your MCP client

Available Tools

All tools accept a chain parameter: ethereum (default) or bsc.

Examples

Check balance on Ethereum: 0xbe0eb53f46cd790cd13851d5eff43d12404d33e8

Analyze whale on BSC: 0xf977814e90da44bfa03b6295a0616a897441acec

Track whale movements above 1000 BNB on BSC

Compare whales: 0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae, 0xbe0eb53f46cd790cd13851d5eff43d12404d33e8

Whale Classifications

Architecture

┌─────────────────────────────────────────────────────┐
│           MCP Server (FastMCP) - 13 Tools           │
└──────────────────────┬──────────────────────────────┘
                       │
        ┌──────────────┴──────────────┐
        │                             │
   BlockchainService            WhaleDetector
   (multi-chain API)            (analysis engine)
        │                             │
        │  async httpx (timeout=30s)  │  classify, score,
        │  rate-limited (5 req/s)     │  discover, track
        │                             │
        └──────────────┬──────────────┘
                       │
             Etherscan V2 API
             (chainid routing)

src/core/
├── server.py             # MCP tool definitions (13 tools)
├── blockchain_service.py # Multi-chain API client
├── whale_detector.py     # Whale analysis engine
├── chains.py             # Chain registry + known addresses
├── validators.py         # Input validation
└── __init__.py           # Public API exports

Adding New Chains

Edit src/core/chains.py and add to CHAIN_REGISTRY:

CHAIN_REGISTRY["polygon"] = ChainConfig(
    name="Polygon",
    symbol="MATIC",
    api_url="https://api.polygonscan.com/api",
    api_key_env="POLYGONSCAN_API_KEY",
    explorer_url="https://polygonscan.com",
    chain_id=137,
)

Chains using Etherscan V2 API (api.etherscan.io/v2/api) share the same API key and use the chainid parameter. Chains with their own API (Polygonscan, Arbiscan, Basescan) need separate API keys.

Optionally add known whale and exchange addresses to KNOWN_WHALES and EXCHANGE_ADDRESSES dicts for richer analysis on the new chain.

Make Commands

make setup        # Create venv, install deps
make run          # Start MCP server
make test         # Run pytest suite
make lint         # Check code style (ruff)
make format       # Auto-format + fix
make check        # Verify config
make clean        # Remove venv
make config-claude # Show Claude Desktop config
make config-codex  # Show Codex config

Configuration

# .env
ETHERSCAN_API_KEY=your_key    # from etherscan.io/myapikey
RATE_LIMIT=5                  # requests/sec (optional, default: 5)

Get a free API key: https://etherscan.io/myapikey

Requirements

• Python 3.10+
• Etherscan API key (free tier: Ethereum only)
• MCP-compatible client (Claude Desktop, Claude Code, GPT Codex, etc.)

Troubleshooting

License

MIT