Ether 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

Chain	Symbol	Chain ID	API	Free Tier
Ethereum	ETH	1	Etherscan V2	Yes
BNB Smart Chain	BNB	56	Etherscan V2	Paid plan only

Expansion-Ready

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

Chain	Symbol	Chain ID	API Key Required
Polygon	MATIC	137	POLYGONSCAN_API_KEY
Arbitrum One	ETH	42161	ARBISCAN_API_KEY
Base	ETH	8453	BASESCAN_API_KEY

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

Tool	Description
check_balance	Get native token balance
get_transactions	Transaction history
get_token_transfers	ERC20/BEP20 transfers
get_contract_abi	Verified contract ABI
get_gas_prices	Current gas prices
get_native_price	ETH/BNB price in USD and BTC
analyze_whale	Full whale analysis with metrics
detect_whale_class	Quick whale classification
compare_whales	Compare multiple addresses
discover_whale_movements	Track large movements
discover_top_whales	Find whales via network analysis
track_exchange_whales	Monitor exchange deposits/withdrawals
list_supported_chains	Show available chains

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

Class	Balance	Description
MEGA WHALE	>= 10,000 tokens	Institutional-level holdings
LARGE WHALE	1,000 - 10,000	Major market participant
MEDIUM WHALE	100 - 1,000	Significant holder
SMALL WHALE	10 - 100	Notable position
SHRIMP	< 10	Retail holder

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

Issue	Solution
Module not found	make setup
API key error	Check .env file
Rate limit hit	Lower RATE_LIMIT in .env
Unknown chain	Run list_supported_chains()
Request timeout	Default 30s - check network/API status
BSC not working	BSC requires Etherscan paid plan

License

MIT