ethcli-mcp 0.2.2

Overview

Exposes 200+ Ethereum tools via the Model Context Protocol (MCP), enabling AI assistants like Claude to query blockchains, analyze transactions, fetch DeFi data, and interact with 50+ data sources. The default MCP surface is read-only for local and remote state changes.

Features

• 230+ MCP tools - Broad ethcli functionality exposed as typed tools, with mutating tools gated by policy
• JSON Schema validation - All tool inputs have schemas for LLM structured output
• Multi-chain support - Ethereum, Polygon, Arbitrum, Optimism, Base, and more
• DEX aggregators - 1inch, CowSwap, LI.FI, KyberSwap, OpenOcean, 0x, Velora, Enso
• Data sources - CoinGecko, DefiLlama, Alchemy, Moralis, Chainlink, Pyth, Dune
• Security tools - GoPlus token analysis, Solodit vulnerability search, bytecode security analysis with dispatcher and handler guard heuristics

Installation

Prerequisites

ethcli must be installed separately. The MCP server spawns ethcli as a subprocess.

cargo install ethcli
ethcli --version

ethcli-mcp looks for ethcli next to the MCP binary. If you use a custom binary location, set ETHCLI_PATH to an absolute path.

Install ethcli-mcp

cargo install ethcli-mcp

Quick Start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ethcli": {
      "command": "ethcli-mcp"
    }
  }
}

With a custom ethcli binary:

{
  "mcpServers": {
    "ethcli": {
      "command": "ethcli-mcp",
      "env": {
        "ETHCLI_PATH": "/absolute/path/to/ethcli"
      }
    }
  }
}

Manual Testing

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | ethcli-mcp

Tool Categories

Environment Variables

Unverified Contract Analysis

The contract_analyze MCP tool exposes ethcli's native unverified-contract workflow. Set follow_proxy, lookup, dispatcher, and checks to inspect proxy implementations, resolve selectors, map selector handlers, and flag side-effecting handler bodies that appear to lack caller gates or calldata hash validation. contract_selectors also supports follow_proxy when you want implementation selectors rather than proxy wrapper selectors.

Equivalent CLI:

ethcli contract analyze 0x... --follow-proxy --lookup --dispatcher --checks --format json

For endpoint diagnostics, endpoints_health returns JSON and defaults to probes: 1 so MCP calls stay bounded. Increase probes when you need a deeper endpoint check.

Architecture

┌─────────────────┐     JSON-RPC      ┌─────────────────┐    subprocess    ┌─────────────┐
│  Claude/LLM     │ ◄──── STDIO ────► │   ethcli-mcp    │ ◄─────────────► │   ethcli    │
└─────────────────┘                   └─────────────────┘                  └─────────────┘

Security

• Read-only by default - Local/remote mutating tools such as config_set_*, address_add, blacklist_add, endpoints_add, chainlist_add, simulate_share, Dune write APIs, Tenderly VNet/admin mutations, and CowSwap create/cancel order are blocked unless ETHCLI_MCP_ENABLE_WRITE_TOOLS=1 is set.
• No raw config disclosure - config_show returns safe config status only. It does not return config file contents because they may contain API keys or private RPC URLs.
• No arbitrary file output - MCP rejects file-output paths for tools such as contract_abi, contract_source, and address_export; omit output to receive data in the tool response.
• No secret-bearing subprocess args - MCP rejects direct credential/header flags such as --show-secrets, --tenderly-key, --alchemy-key, --etherscan-api-key, --rpc-header, and --fork-header. Configure credentials via environment variables or ethcli config instead.
• Success-output redaction - Credential-bearing URLs and secret-looking header/config lines are redacted before returning MCP tool responses.
• Process-group cleanup - Timed-out subprocesses are killed as a process group so child tools such as anvil do not remain running.
• Rate limiting - Max 10 concurrent subprocesses
• Timeouts - 10 seconds for fast local commands, 30 seconds for network commands
• Input validation - Argument length limits, null byte detection
• Error sanitization - API keys filtered from error messages

Development

See CONTRIBUTING.md for guidelines.

cargo build -p ethcli-mcp
cargo test -p ethcli-mcp --test integration

License

MIT