kosyak-evm-mcp-server

Model Context Protocol server for interacting with 119+ EVM blockchains from Claude Code or any MCP client. 50 tools, 10 prompts, 119 networks.

Highlights

• Full EVM coverage — reads, writes, history, event logs, contract analysis, NFT tradability, gas estimation, signing
• Zero-config contract reads — read_contract auto-fetches ABI, auto-resolves proxies, auto-decodes reverts; multicall batches reads via Multicall3
• Historical state + overrides — read_contract / get_storage_at / read_storage_batch accept any blockNumber or block tag; simulate_call and read_contract accept stateOverride to test "what if X were Y" without sending
• Verified source navigation — get_contract_source supports grep (ripgrep-style), files, index modes to avoid 200KB+ dumps of multi-file Solidity sources
• Proxy-aware — auto-detects 6 patterns (EIP-1967 Transparent/UUPS, Beacon, EIP-1167 Minimal, Solady CWIA, Zeppelinos-classic, EIP-1822) and returns merged ABI
• 47+ events auto-decoded — Uniswap V2/V3/V4, Aave V3, Compound V2/V3, Seaport, Lido, ERC20/721/1155, OpenZeppelin admin events
• Pre-flight simulation + revert cascade — simulate_transaction accepts {functionName, args, abiJson?} for safe encoding; on revert returns firstRevertedCall (DFS-walked trace trees) decoded via cascade: Panic/Error → contract ABI → impl ABI → openchain.xyz → 4byte. Auto-falls back to native eth_call on chains Tenderly doesn't support
• Unverified contract toolkit — find_recent_calls reverse-engineers ABIs from on-chain calldata (per-slot type heuristics, signature lookup); decompile_local shells out to a local heimdall (opt-in via HEIMDALL_PATH); encode_calldata / compute_selector for hand-crafted bytes
• Semantic tx summaries — get_transaction_receipt returns assetSummary bucketing transfers/mints/burns/approvals/swaps; get_address_history returns valueSummary with totalIn/totalOut/net; get_gas_price exposes typicalCosts for common operations
• NFT tradability (ERC721 + ERC1155) — open / likely_soulbound / marketplace_only / frozen via simulation + ground-truth Transfer-log evidence; standard auto-detected, ERC721 cross-checks transferFrom and safeTransferFrom
• EIP-7702 + ERC-1271 — EOA delegation detection, smart-wallet signature verification (Safe, ZeroDev, Biconomy, Solady)
• Free-tier friendly — get_logs auto-chunks wide block ranges when Alchemy rejects them, with rate-limit retry
• Write safety — 3 layers: DRY_RUN default, mainnet block, explicit confirm: "CONFIRMED"
• Parallel-write safe — per-wallet nonce manager + optional nonce/gas/maxFeePerGas overrides; send_raw_transaction for replace-by-fee and pre-signed flows

Quick Start

Add to ~/.claude.json (or project-level .claude.json).

Windows

{
  "mcpServers": {
    "evm": {
      "type": "stdio",
      "command": "npx.cmd",
      "args": ["-y", "kosyak-evm-mcp-server"],
      "env": {
        "EVM_PRIVATE_KEY": "",
        "ETHERSCAN_API_KEY": "",
        "ALCHEMY_API_KEY": "",
        "TENDERLY_RPC_URLS": "",
        "ALLOW_MAINNET_WRITE": "false",
        "HEIMDALL_PATH": ""
      }
    }
  }
}

macOS / Linux

{
  "mcpServers": {
    "evm": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kosyak-evm-mcp-server"],
      "env": {
        "EVM_PRIVATE_KEY": "",
        "ETHERSCAN_API_KEY": "",
        "ALCHEMY_API_KEY": "",
        "TENDERLY_RPC_URLS": "",
        "ALLOW_MAINNET_WRITE": "false",
        "HEIMDALL_PATH": ""
      }
    }
  }
}

Leave unused keys as empty strings — they will be ignored. Restart Claude Code after saving.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | EVM_PRIVATE_KEY | For writes | Private key (0x prefix optional) | | ETHERSCAN_API_KEY | Recommended | Contract ABIs, tx history, token/NFT transfers | | ALCHEMY_API_KEY | Optional | Premium RPC (fallback to public RPCs) | | TENDERLY_RPC_URLS | Optional | Transaction tracing — comma-separated gateway URLs (one per network). Get them at Tenderly Dashboard → Node → Create Gateway | | ALLOW_MAINNET_WRITE | Optional | Enable real mainnet transactions, including send_raw_transaction (default: false) | | HEIMDALL_PATH | Optional | Path to a local heimdall binary used by decompile_local (defaults to heimdall in PATH) |

All address parameters accept ENS names (vitalik.eth).

Tools (50)

Chain & Wallet

| Tool | Description | |------|-------------| | get_wallet_address | Current wallet address | | get_chain_info | Chain ID, block number, RPC | | get_supported_networks | All supported networks | | get_gas_price | Base fee + priority fee + typicalCosts (ETH/ERC20/Uniswap V2/V3 operation costs) | | estimate_gas | Preview gas + ETH cost before sending |

ENS

| Tool | Description | |------|-------------| | resolve_ens_name | ENS name → address | | lookup_ens_address | Address → ENS name |

Blocks

| Tool | Description | |------|-------------| | get_block | Block by number/hash. Compact by default; includeTransactions, includeBurnedFee flags. Always shows timestamp_msk | | get_latest_block | Latest block, same params as get_block |

Balances & NFT

| Tool | Description | |------|-------------| | get_balance | Native token balance (ETH/MATIC/etc.) | | get_token_balance | ERC20 balance | | get_allowance | ERC20 allowance with formatted + isInfinite flag | | get_erc1155_balance | ERC1155 balance | | get_nft_info | ERC721 metadata URI; resolveMetadata: true fetches JSON | | nft_recent_activity | Transfer/Mint/Burn summary for ERC721 + ERC1155 collections, auto-chunks under free-tier RPC limits | | nft_check_transferability | ERC721 + ERC1155 cascade (sim → validator → ground-truth Transfer scan). Returns classification + confidence + proofs. Standard auto-detected via ERC-165; ERC721 cross-checks transferFrom and safeTransferFrom |

Transactions

| Tool | Description | |------|-------------| | get_transaction | Tx details + auto-decoded calldata (12 common selectors) | | get_transaction_receipt | Receipt + auto-decoded events + assetSummary (transfers/mints/burns/approvals/swaps buckets) | | wait_for_transaction | Wait for confirmation, includes assetSummary | | get_transaction_trace | Tenderly full trace; summary=true for compact output | | decode_transaction_input | Decode calldata via Tenderly (no ABI needed) | | simulate_transaction | Tenderly simulate (full trace, asset/balance changes, logs). Accepts {functionName, args, abiJson?} for safe encoding. On revert exposes decodedInput + firstRevertedCall + revertClassification. Auto-falls back to native eth_call when Tenderly does not support the chain | | simulate_call | Native eth_call with stateOverride (fake balance/nonce/code/storage before the call). No Tenderly. Faster + free; returns success/revert + return data, no trace | | wait_for_storage_value | Poll a slot until it matches expected or change: true. Useful for waiting on flag flips |

Event Logs

| Tool | Description | |------|-------------| | get_logs | Query logs with auto-decoding of 47+ event signatures. Pass eventSignature for auto-topic0 computation. autoChunk: 'onError' (default), chunkSize/maxChunks to tune |

History (Etherscan)

| Tool | Description | |------|-------------| | get_address_history | History by type: native, internal, erc20, erc721, erc1155. Adds valueSummary (totalIn/totalOut/net) for native + erc20 | | find_recent_calls | Pull recent successful txs to a contract, group by selector, dump per-slot calldata samples + heuristic type hints. Reverse-engineer ABIs from on-chain ground truth |

Contracts & Pricing

| Tool | Description | |------|-------------| | get_contract_abi | Auto proxy resolution; returns abi (proxy ∪ impl, impl wins) + proxyAbi/implAbi/proxyInfo | | get_contract_source | Verified Solidity source. fields, index, files, grep (ripgrep-style) — avoids dumping 200KB+ of multi-file source | | get_contract_creation | Creator + creation tx hash (up to 5 contracts per call) | | get_contract_interfaces | ERC-165 detection (ERC-721/1155/2981, AccessControl, Seaport) batched via Multicall3 | | get_token_metadata | Composite: name + symbol + decimals + totalSupply + proxy + verified in one call | | get_code | Bytecode + classification: EOA / EIP-7702 delegated / contract | | decompile_local | Run a locally-installed heimdall against the contract's bytecode. Opt-in: requires heimdall in PATH or HEIMDALL_PATH. Thin passthrough — no post-processing | | get_proxy_implementation | Detect proxy type and return implementation | | get_storage_at | Raw storage slot + interpretations (asAddress/asUint256/asBool/isEmpty). Optional blockNumber for historical reads | | read_storage_batch | Read many storage slots at one block. slots[] or start+count range mode (capped at 256) | | read_contract | Call view functions (auto-fetches ABI). On revert auto-decodes via cascade. Optional from, blockNumber, value, stateOverride | | multicall | Batch reads via Multicall3 | | compute_selector | Compute 4-byte selector / 32-byte topic locally (keccak256, no RPC) | | encode_calldata | Build ABI-encoded calldata from a function signature + args (no RPC). Symmetric to decode_transaction_input | | get_token_price | CoinGecko price by ticker or ID |

Write (DRY_RUN by default)

| Tool | Description | |------|-------------| | transfer_native | Send ETH/native tokens. Accepts optional nonce, gas, gasPriceGwei, maxFeePerGasGwei, maxPriorityFeePerGasGwei | | transfer_erc20 | Send ERC20 tokens. Same override params as transfer_native | | approve_token_spending | Approve ERC20 spender. infinite: true for max uint256 | | write_contract | Call any contract function. Same override params as transfer_native | | send_raw_transaction | Broadcast a pre-signed raw tx. Bypasses the per-wallet nonce manager and DRY_RUN simulation — for replace-by-fee / pre-signed flows | | sign_message | Sign arbitrary messages (SIWE, off-chain) | | sign_typed_data | Sign EIP-712 typed data (permits, meta-txs) | | verify_signature | Verify signature; supports ERC-1271 smart wallets via viem |

Examples

"What's my ETH balance on mainnet and Polygon?"
"Show my last 10 transactions and total ETH flow"
"What proxy pattern does USDC use and what's the implementation?"
"Find every Solidity file in this contract that mentions onlyOwner"
"Is this address a smart wallet, EOA, or EIP-7702 delegation?"
"Decode this transaction — what did it actually do?"
"Simulate sending 1 ETH to alice.eth — will it succeed?"
"Show all Uniswap V3 swaps in the USDC/WETH pool over the last 10 blocks"
"Give infinite USDC approval to Uniswap router"

Event Auto-Decoding

get_logs and get_transaction_receipt decode known event signatures into human-readable form:

• ERC20/721/1155 — Transfer, Approval, ApprovalForAll, TransferSingle, TransferBatch (Mint/Burn detection via zero address)
• WETH — Deposit, Withdrawal
• Uniswap V2 — Swap, Sync, Mint/Burn (LP)
• Uniswap V3 — Swap, Flash
• Uniswap V4 — Swap, Initialize, ModifyLiquidity
• ERC-4626 Vaults — Deposit, Withdraw
• Aave V3 — Supply, Borrow, Repay, Withdraw, LiquidationCall, FlashLoan
• Balancer V2 — FlashLoan
• Compound V2 — Mint, Redeem, Borrow, RepayBorrow, LiquidateBorrow
• Compound V3 (Comet) — Supply, Withdraw, SupplyCollateral, WithdrawCollateral, AbsorbDebt, BuyCollateral
• Lido (stETH) — Submitted, TransferShares
• Seaport (OpenSea) — OrderFulfilled, OrderCancelled, OrdersMatched, CounterIncremented
• Admin (OpenZeppelin) — OwnershipTransferred, Paused, Unpaused, RoleGranted, RoleRevoked, Initialized

Security

Write operations use a 3-layer protection model:

1. DRY_RUN default — every write simulates first, returns gas estimate, zero risk
2. Mainnet block — real mainnet txs disabled unless ALLOW_MAINNET_WRITE=true
3. Explicit confirm — real execution requires confirm: "CONFIRMED"

send_raw_transaction bypasses the per-wallet nonce manager and DRY_RUN gas simulation — the caller is responsible for the bytes. The ALLOW_MAINNET_WRITE and DRY_RUN-by-default policies still apply.

Networks (119)

Mainnets: Ethereum, Polygon, Arbitrum, Optimism, Base, BSC, Avalanche, zkSync, Linea, Scroll, Mantle, Blast, Celo, Gnosis, Fantom, Filecoin, Moonbeam, Cronos, Aurora, Canto, Flow, Ronin, SEI, Astar, ApeChain, Manta, Fraxtal, Mode, Metis, Kroma, Zora, opBNB, Ink, Unichain, Abstract, Anime Chain, Monad, MegaETH

Testnets: Sepolia, Holesky, Optimism Sepolia, Arbitrum Sepolia, Base Sepolia, Polygon Amoy, Avalanche Fuji, BSC Testnet, zkSync Sepolia, Linea Sepolia, Scroll Sepolia, MegaETH Testnet, and more — plus local: Hardhat, Anvil, Ganache.

Development

git clone https://github.com/kosyakdev/evm-mcp-server
cd evm-mcp-server
npm install
npx tsc --noEmit   # typecheck
bun run build      # build to build/
npm start          # run stdio server

Releases are automated via GitHub Actions — bump the version in package.json and push to main, and CI publishes to npm. See CLAUDE.md for details.

License

MIT