ChainRPC MCP

ChainRPC MCP

JSON-RPC MCP server for EVM chains and Bitcoin

A safety-first Model Context Protocol server for EVM chains and Bitcoin.

ChainRPC MCP gives agents a focused set of tools for balances, blocks, transactions, logs, smart-contract reads, gas and fee estimation, and transaction decoding. It can submit already-signed transactions, but only behind explicit, disabled-by-default safety gates. It never accepts private keys, manages wallets, or signs transactions.

• Two ecosystems, one server: EVM JSON-RPC and Bitcoin Core-compatible RPC.
• Useful without an account: defaults to public Ethereum and Bitcoin endpoints from PublicNode.
• Bring your own infrastructure: replace either endpoint and optionally use HTTP Basic authentication.
• Official transports: local stdio and stateful Streamable HTTP through the official MCP SDK.
• Constrained by design: no arbitrary RPC passthrough and no wallet, admin, debug, miner, or node-management methods.

Choose how to connect

Hosted, read-only service

The public endpoint is available now:

https://chainrpc-mcp.mitander.io/mcp

For clients that accept a remote Streamable HTTP server:

{

"mcpServers": { "chainrpc-mcp": { "url": "https://chainrpc-mcp.mitander.io/mcp" } } }

Health and upstream status:

curl 'https://chainrpc-mcp.mitander.io/health?upstream=1'

The hosted service is shared, rate-limited, and intentionally has both broadcast features disabled. It is suitable for evaluation and public-chain reads, but has no availability SLA. Requests are visible to the service operator and upstream RPC providers; use your own deployment for sensitive queries or production workloads.

Local stdio server

Requirements: Node.js 20 or newer.

npx -y chainrpc-mcp

Example client configuration:

{

"mcpServers": { "chainrpc-mcp": { "command": "npx", "args": ["-y", "chainrpc-mcp"], "env": { "EVM_RPC_URL": "https://ethereum-rpc.publicnode.com", "BITCOIN_RPC_URL": "https://bitcoin-rpc.publicnode.com" } } } }

The RPC variables are optional; they are shown to make the defaults explicit.

Available tools

EVM

Any HTTP(S) EVM JSON-RPC endpoint can be used, so the same tools work with Ethereum mainnet, testnets, and compatible chains. Results always come from the configured endpoint; callers should inspect evm_getChainInfo before making chain-specific assumptions.

Bitcoin

Bitcoin Core is not an address indexer. btc_getAddressBalance uses scantxoutset, which reports currently unspent, confirmed outputs—not history or unconfirmed balance. Only one scan can run on a node at a time, so a shared endpoint may return scan already in progress. Use a dedicated node for frequent address scans.

Safety model

ChainRPC MCP treats transaction submission as an exceptional operation:

• Broadcasting is off unless ALLOW_EVM_BROADCAST or ALLOW_BITCOIN_BROADCAST is explicitly enabled.
• The server accepts only serialized, already-signed transaction bytes.
• Every broadcast call requires the literal confirmation I understand this broadcasts a real transaction.
• EVM submission checks the endpoint and transaction chain IDs, rejects unprotected legacy transactions, recovers the signer, and runs eth_estimateGas first.
• Bitcoin submission checks the endpoint network and requires testmempoolaccept to approve the transaction.
• Submission requests are never automatically retried. A timeout can leave broadcast status ambiguous.
• Read inputs use strict schemas; upstream concurrency, timeout, retry, and response sizes are bounded.
• HTTP mode validates hosts and browser origins, supports bearer authentication, caps request bodies, and binds to loopback by default.

RPC responses are untrusted external data. A compromised endpoint can lie about chain state, censor requests, or observe queries. Independently verify high-value decisions, ideally against infrastructure you control.

See SECURITY.md for vulnerability reporting and the complete trust boundary.

Configuration

Copy example.env to .env when running from a checkout.

GETH_URL remains a deprecated compatibility alias for EVM_RPC_URL. Credentials embedded in RPC URLs are rejected; use the matching username and password variables.

Self-host with Streamable HTTP

Start a loopback-only HTTP server:

npm start

curl 'http://127.0.0.1:3000/health?upstream=1'

To bind beyond loopback, explicitly set the host allowlist and authentication:

HOST=0.0.0.0 \

ALLOWED_HOSTS=mcp.example.com \ MCP_AUTH_TOKEN='replace-with-a-long-random-secret' \ npm start

Terminate TLS at a trusted reverse proxy, preserve the original Host header, and keep the origin private. A bearer token is useful for a single trusted client; use an OAuth-capable gateway and network access policy for multi-user deployments.

Docker defaults to stdio. Override the command for HTTP:

docker build -t chainrpc-mcp .

docker run --rm -p 127.0.0.1:3000:3000 \ -e HOST=0.0.0.0 \ -e ALLOWED_HOSTS=localhost,127.0.0.1 \ -e MCP_AUTH_TOKEN='replace-with-a-long-random-secret' \ chainrpc-mcp --http

Production service topology:

MCP client

| v Cloudflare edge -> outbound-only Cloudflare Tunnel -> nginx on loopback | v ChainRPC MCP / \ v v EVM RPC Bitcoin RPC

Deployment units, nginx configuration, hardening details, and operating commands are in docs/OPERATIONS.md.

Development

git clone https://github.com/John0n1/chainrpc-mcp.git

cd chainrpc-mcp npm ci npm run check npm run test:coverage

Useful commands:

The detailed design and remediation record is in docs/AUDIT.md. Contributions are welcome through issues and pull requests. Please use a private GitHub security advisory—not a public issue—for suspected vulnerabilities.

License

MIT