Ethereum RPC MCP Server

Connect an MCP client to Ethereum or another EVM chain through an HTTP JSON-RPC endpoint. The server provides 13 focused read/simulation tools, a generic RPC tool, and a configuration resource. It runs over stdio and supports both older MCP clients and the 2026-07-28 protocol through the MCP TypeScript SDK.

The npm package and executable retain the historical spelling ethereum-rpc-mpc for compatibility. The protocol is MCP.

Requirements and installation

Requires Node.js 22 or newer. CI covers Node 22, 24 and 26.

npx -y ethereum-rpc-mpc [RPC_URL] [CHAIN_NAME]

To build and run from source:

git clone https://github.com/Kemperino/ethereum-rpc-mpc.git
cd ethereum-rpc-mpc
yarn install --frozen-lockfile
yarn build
node dist/server/index.js https://ethereum-rpc.publicnode.com Ethereum

The default endpoint is https://ethereum-rpc.publicnode.com. Supply your own provider URL or local node when you need dedicated capacity, archive data, or provider-specific methods. Each server process connects to one endpoint.

MCP client configuration

For a client that accepts mcpServers configuration, launch the built checkout with an absolute path:

{
  "mcpServers": {
    "ethereum": {
      "command": "node",
      "args": ["/absolute/path/to/ethereum-rpc-mpc/dist/server/index.js"],
      "env": {
        "ETH_RPC_URL": "https://ethereum-rpc.publicnode.com",
        "ETH_CHAIN_NAME": "Ethereum",
        "ETH_RPC_TIMEOUT_MS": "30000"
      }
    }
  }
}

Alternatively, use "command": "npx" and "args": ["-y", "ethereum-rpc-mpc"] to run the npm package instead. Keep private provider URLs in your client's local environment configuration.

You can also pass positional arguments or named flags:

node dist/server/index.js http://127.0.0.1:8545 Local
node dist/server/index.js --rpc-url https://ethereum-rpc.publicnode.com --chain-name Ethereum --timeout-ms 15000
node dist/server/index.js --help
node dist/server/index.js --version

Explicit arguments override environment variables. Timeout values must be integers from 1 to 300000 milliseconds. URLs must use HTTP(S), without embedded username/password or fragments. Startup does not contact the RPC provider; failures are reported when a tool is used. A configured chain name is only a label: use eth_chain_id to verify the network.

Tools

All focused tools are annotated as read-only. eth_call and eth_estimate_gas simulate execution without broadcasting a transaction.

Tool	Purpose
`eth_chain_id`	Verify the connected chain
`eth_block_number`	Read the current head block number
`eth_get_balance`	Read a native currency balance in wei
`eth_get_transaction_count`	Read an account nonce, including pending state
`eth_get_code`	Read deployed bytecode
`eth_get_storage_at`	Read a contract storage slot
`eth_get_block`	Read a block by number, tag or hash, with optional full transactions
`eth_get_transaction`	Read a transaction by hash
`eth_get_transaction_receipt`	Read execution status, gas usage and logs
`eth_get_logs`	Query event logs with address, topic and block filters
`eth_call`	Simulate ABI-encoded calldata, optionally with state overrides
`eth_estimate_gas`	Estimate transaction gas units
`eth_fee_history`	Read base fees, gas usage ratios and priority-fee percentiles
`eth_json_rpc_call`	Call any RPC method supported by the provider

The generic tool can execute state-changing methods, including transaction submission and node/account operations if the provider exposes them. Its MCP annotations reflect this. The server does not hold private keys or sign transactions. Restrict your endpoint's methods if you need an entirely read-only setup.

Successful tool results preserve the provider's JSON values in structuredContent.result and JSON text content. Quantities remain hex strings, including values too large for JavaScript numbers. Unknown or pending receipts can return null; this is not a tool failure. RPC failures return isError: true, with the provider's error code and data when available.

Examples of tool arguments

Read a balance at a finalized block:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "block": "finalized"
}

Call eth_call with pre-encoded ERC-20 totalSupply() calldata:

{
  "transaction": {
    "to": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
    "data": "0x18160ddd"
  },
  "block": "latest"
}

Call eth_get_logs over a specific range:

{
  "filter": {
    "address": "0x6B175474E89094C44Da98b954EedeAC495271d0F",
    "fromBlock": "0x1234000",
    "toBlock": "0x1234010"
  }
}

The generic tool accepts arbitrary positional JSON values, including objects and booleans:

{
  "method": "eth_getBlockByNumber",
  "params": ["latest", true]
}

Block tags include latest, earliest, pending, safe and finalized. State reads also accept EIP-1898 objects such as {"blockHash": "0x<64 hex digits>", "requireCanonical": true}. For eth_get_block, use {"block": {"blockHash": "0x<64 hex digits>"}} to select a hash.

Log topics use positional AND, nested arrays for OR, and null as a wildcard. A log filter's blockHash cannot be combined with fromBlock or toBlock. Fee-history blockCount is a decimal integer (1–1024); most other numeric RPC inputs are minimal hex quantities such as 0x0 or 0x10.

Behavior and limits

text://rpc_info reports the configured label, endpoint origin, and timeout. It omits URL paths and query strings because they can contain API keys.
Calls have a 30-second default deadline, honor MCP cancellation, and limit each RPC response to 10 MiB. Narrow log ranges or request transaction hashes if a response is too large.
Requests are never automatically retried. A timeout on transaction submission does not establish whether the provider accepted it.
Provider errors, limits and method support still apply. Historical state may require an archive node. There is no automatic pagination, failover, indexing, ENS resolution, ABI encoding/decoding, or WebSocket subscription support.
New Ethereum result fields are passed through unchanged. Transaction simulation accepts additional JSON fields, including provider extensions; the generic tool remains available for new RPC methods.

Development

With Nix installed and nix-command and flakes enabled, enter a development shell with Node.js 24 (including npm) and Yarn 1.22.22:

nix develop

The committed flake.lock pins the toolchain for macOS and Linux on Apple Silicon/ARM64 and x86-64. Entering the shell does not install JavaScript dependencies; run the commands below explicitly. To run a command without entering an interactive shell, use nix develop --command yarn test after installing dependencies. Update the Nixpkgs pin with nix flake update nixpkgs.

yarn install --frozen-lockfile
yarn typecheck
yarn test
yarn inspector
npm pack --dry-run

Tests use local mock RPC endpoints and real MCP stdio clients; they need loopback socket access but no external RPC credentials. They cover both protocol generations, structured parameters, tool dispatch, input validation, malformed provider replies, errors, deadlines, cancellation, and credential-safe configuration reporting.

Builds clear dist first so removed features cannot survive in a package as stale JavaScript. Only compiled files, package metadata, README and license are distributed. TypeScript and the MCP test client are development dependencies.

Migration and release

See CHANGELOG.md. Version 2.0.0 introduces these compatibility changes:

Node 22+ replaces the previous unspecified runtime requirement.
Zircuit-specific tools and automatic chain detection are removed.
SQLite analytics, --analytics and --db-path are removed. Old flags now fail with a configuration error.
rpc_info now returns JSON with an endpoint origin instead of the full RPC URL.
The default RPC provider is PublicNode. Explicit endpoints and the generic tool name remain supported.

The publish workflow runs on published stable GitHub releases, verifies that the tag is exactly v<package.json version>, installs the frozen lockfile, type-checks, tests and checks the package before publishing with the existing NPM_TOKEN secret. Prereleases are skipped. Before publishing, update the package version and changelog in a separate release commit and confirm that CI and npm credentials are working.

References

License

MIT. See LICENSE.md.