ChainRPC MCP

Official18 tools

by John0n1 · JavaScript

Safety-first EVM and Bitcoin RPC tools for balances, contracts, blocks, and transactions

JSON-RPC MCP server providing safety-first tools for EVM chains and Bitcoin. It supports operations for balances, contracts, blocks, and transactions, exposing functionality via MCP. The repository targets a Node.js environment and is published as an npm package.

🛠️ Key Features

JSON-RPC MCP server
EVM chain tooling
Bitcoin RPC tooling
Safety-first behavior

🚀 Use Cases

Retrieve balances
Interact with contracts
Query blocks
Work with transactions

⚡ Developer Benefits

Node.js / MCP server integration
JSON-RPC alignment for RPC-style workflows
Repository-focused documentation and CI-backed package releases

⚠️ Limitations

Limited to RPC-style balance, contract, block, and transaction access as described
Slug: io-github-john0n1-chainrpc-mcp
Topics: blockchain, ethereum, geth, geth-rpc, javascript, json-rpc, mcp, mcp-server, nodejs, server, nethermind
Tool count: 18

Topics

blockchainethereumgethgeth-rpcjavascriptjson-rpcmcpmcp-servernodejsservernethermind

Captured live from the server via tools/list.

evm_getBlockNumber

Return the latest EVM block number from the configured endpoint.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

evm_getChainInfo

Return the EVM chain ID and upstream client version.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

evm_getNativeBalance

Read an address native-token balance at an EVM block without requiring a wallet.

Parameters2

address	string	required
block	string \| number	optional	Block number or latest, earliest, pending, safe, or finalized

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string"
    },
    "block": {
      "type": [
        "string",
        "number"
      ],
      "description": "Block number or latest, earliest, pending, safe, or finalized"
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

evm_getBlock

Read an EVM block by number, tag, or block hash.

Parameters2

block	any	required
includeTransactions	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "block": {
      "anyOf": [
        {
          "type": [
            "string",
            "number"
          ]
        },
        {
          "type": "string",
          "pattern": "^0x[0-9a-fA-F]{64}$"
        }
      ]
    },
    "includeTransactions": {
      "type": "boolean",
      "default": false
    }
  },
  "required": [
    "block"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

evm_getTransaction

Read an EVM transaction and its receipt by transaction hash.

Parameters1

hash

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "hash": {
      "type": "string",
      "pattern": "^0x[0-9a-fA-F]{64}$"
    }
  },
  "required": [
    "hash"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

evm_call

Run a read-only eth_call with pre-encoded calldata. This never submits a transaction.

Parameters5

to	string	required
data	string	optional
from	any	optional
valueWei	string \| number	optional
block	string \| number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "to": {
      "type": "string"
    },
    "data": {
      "type": "string",
      "pattern": "^0x(?:[0-9a-fA-F]{2})*$",
      "default": "0x"
    },
    "from": {
      "$ref": "#/properties/to"
    },
    "valueWei": {
      "type": [
        "string",
        "number"
      ]
    },
    "block": {
      "type": [
        "string",
        "number"
      ]
    }
  },
  "required": [
    "to"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

evm_readContract

Encode, execute, and decode a read-only smart-contract function using a supplied JSON ABI.

Parameters5

address	string	required
abi	array	required	JSON ABI entries needed for this function
functionName	string	required
args	array	optional
block	string \| number	optional

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string"
    },
    "abi": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": {}
      },
      "minItems": 1,
      "description": "JSON ABI entries needed for this function"
    },
    "functionName": {
      "type": "string",
      "minLength": 1
    },
    "args": {
      "type": "array",
      "default": []
    },
    "block": {
      "type": [
        "string",
        "number"
      ]
    }
  },
  "required": [
    "address",
    "abi",
    "functionName"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

evm_estimateTransaction

Estimate gas for an unsigned EVM transaction. Values are accepted as decimal or hex quantities.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

evm_getLogs

Read EVM event logs using an address/topics filter and bounded block range.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

evm_broadcastTransaction

Preflight and broadcast an already-signed EVM transaction. Disabled unless ALLOW_EVM_BROADCAST=true; never signs or stores keys.

Parameters3

rawTransaction	string	required
expectedChainId	integer	required
confirmation	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "rawTransaction": {
      "type": "string",
      "pattern": "^0x(?:[0-9a-fA-F]{2})*$"
    },
    "expectedChainId": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "confirmation": {
      "type": "string",
      "const": "I understand this broadcasts a real transaction"
    }
  },
  "required": [
    "rawTransaction",
    "expectedChainId",
    "confirmation"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

btc_getBlockchainInfo

Return Bitcoin network, chain height, sync, and pruning information.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

btc_getAddressBalance

Scan the Bitcoin UTXO set for an address and return its confirmed spendable outputs. This is not address history and shared RPC nodes may reject concurrent scans.

Parameters1

address

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "minLength": 14,
      "maxLength": 90,
      "pattern": "^[a-zA-Z0-9]+$"
    }
  },
  "required": [
    "address"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

btc_getBlock

Read a Bitcoin block by height or hash with selectable verbosity.

Parameters2

block	any	required
verbosity	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "block": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0
        },
        {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{64}$"
        }
      ]
    },
    "verbosity": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3,
      "default": 1
    }
  },
  "required": [
    "block"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

btc_getTransaction

Read a raw Bitcoin transaction by txid. A block hash can make confirmed transaction lookup more reliable.

Parameters2

txid	string	required
blockHash	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "txid": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$"
    },
    "blockHash": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$"
    }
  },
  "required": [
    "txid"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

btc_getTxOut

Read an unspent Bitcoin transaction output. Returns null when the output is spent or unknown.

Parameters3

txid	string	required
vout	integer	required
includeMempool	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "txid": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{64}$"
    },
    "vout": {
      "type": "integer",
      "minimum": 0
    },
    "includeMempool": {
      "type": "boolean",
      "default": true
    }
  },
  "required": [
    "txid",
    "vout"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

btc_estimateFee

Estimate a Bitcoin fee rate for confirmation within a target number of blocks.

Parameters2

confirmationTarget	integer	required
mode	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "confirmationTarget": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1008
    },
    "mode": {
      "type": "string",
      "enum": [
        "economical",
        "conservative"
      ],
      "default": "conservative"
    }
  },
  "required": [
    "confirmationTarget"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

btc_decodeRawTransaction

Decode a serialized Bitcoin transaction without broadcasting it.

Parameters1

rawTransaction

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "rawTransaction": {
      "type": "string",
      "pattern": "^(?:[0-9a-fA-F]{2})+$"
    }
  },
  "required": [
    "rawTransaction"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

btc_broadcastTransaction

Validate and broadcast an already-signed Bitcoin transaction. Disabled unless ALLOW_BITCOIN_BROADCAST=true; never signs or stores keys.

Parameters4

rawTransaction	string	required
expectedNetwork	string	required
maxFeeRateBtcPerKvB	number	optional
confirmation	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "rawTransaction": {
      "type": "string",
      "pattern": "^(?:[0-9a-fA-F]{2})+$"
    },
    "expectedNetwork": {
      "type": "string",
      "enum": [
        "main",
        "test",
        "signet",
        "regtest"
      ]
    },
    "maxFeeRateBtcPerKvB": {
      "type": "number",
      "minimum": 0
    },
    "confirmation": {
      "type": "string",
      "const": "I understand this broadcasts a real transaction"
    }
  },
  "required": [
    "rawTransaction",
    "expectedNetwork",
    "confirmation"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md10 KBView on GitHub

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:

text

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

For clients that accept a remote Streamable HTTP server:

json

{
  "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:

json

{
  "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

Tool	Purpose	State-changing
`evm_getBlockNumber`	Return the latest block number	No
`evm_getChainInfo`	Return chain ID and client version	No
`evm_getNativeBalance`	Read a native-token balance at a block	No
`evm_getBlock`	Read a block by number, tag, or hash	No
`evm_getTransaction`	Read a transaction and receipt	No
`evm_call`	Execute an `eth_call` with encoded calldata	No
`evm_readContract`	Encode, call, and decode a function from its ABI	No
`evm_estimateTransaction`	Estimate gas for an unsigned transaction	No
`evm_getLogs`	Query event logs with address and topic filters	No
`evm_broadcastTransaction`	Preflight and submit signed transaction bytes	Yes

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

Tool	Purpose	State-changing
`btc_getBlockchainInfo`	Return network, height, sync, and pruning information	No
`btc_getAddressBalance`	Scan confirmed UTXOs for an address	No
`btc_getBlock`	Read a block by height or hash	No
`btc_getTransaction`	Read raw transaction details	No
`btc_getTxOut`	Look up an unspent transaction output	No
`btc_estimateFee`	Estimate a fee rate for a confirmation target	No
`btc_decodeRawTransaction`	Decode serialized transaction bytes	No
`btc_broadcastTransaction`	Validate and submit signed transaction bytes	Yes

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.

Variable	Default	Description
`EVM_RPC_URL`	`https://ethereum-rpc.publicnode.com`	Any HTTP(S) EVM JSON-RPC endpoint
`BITCOIN_RPC_URL`	`https://bitcoin-rpc.publicnode.com`	Any HTTP(S) Bitcoin Core-compatible endpoint
`EVM_RPC_USERNAME` / `EVM_RPC_PASSWORD`	unset	Optional EVM HTTP Basic authentication pair
`BITCOIN_RPC_USERNAME` / `BITCOIN_RPC_PASSWORD`	unset	Optional Bitcoin HTTP Basic authentication pair
`RPC_TIMEOUT_MS`	`12000`	Per-attempt upstream timeout
`RPC_RETRIES`	`1`	Retry count for retryable reads only
`RPC_MAX_RESPONSE_BYTES`	`10000000`	Maximum upstream response body
`RPC_MAX_CONCURRENCY`	`20`	Maximum concurrent requests per chain client
`ALLOW_EVM_BROADCAST`	`false`	Enable signed EVM transaction submission
`ALLOW_BITCOIN_BROADCAST`	`false`	Enable signed Bitcoin transaction submission
`TRANSPORT`	`stdio`	Default transport: `stdio` or `http`
`HOST` / `PORT`	`127.0.0.1` / `3000`	HTTP bind address and port
`MCP_PATH`	`/mcp`	Streamable HTTP MCP path
`MCP_AUTH_TOKEN`	unset	Optional bearer token for `/mcp`
`ALLOWED_HOSTS`	unset	Required allowlist when binding HTTP to a non-loopback address
`CORS_ORIGINS`	unset	Comma-separated browser-origin allowlist
`MAX_MCP_SESSIONS`	`1000`	Maximum concurrent HTTP MCP sessions
`HTTP_BODY_LIMIT`	`1mb`	Express request-body limit

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:

text

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:

Command	Purpose
`npm run start:stdio`	Start the stdio transport
`npm start`	Start Streamable HTTP
`npm run dev`	Start HTTP with Node watch mode
`npm test`	Run the test suite
`npm run check`	Syntax-check the entry point and run all tests
`npm pack --dry-run`	Inspect the npm package contents

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

Install

Tools (18)

evm_getBlockNumberevm_getChainInfoevm_getNativeBalanceevm_getBlockevm_getTransactionevm_callevm_readContractevm_estimateTransaction

Configuration

Environment variables

EVM_RPC_URLdefault https://ethereum-rpc.publicnode.com

EVM JSON-RPC endpoint

BITCOIN_RPC_URLdefault https://bitcoin-rpc.publicnode.com

Bitcoin Core-compatible JSON-RPC endpoint

ALLOW_EVM_BROADCASTdefault false

Explicitly enable signed EVM transaction broadcasts

ALLOW_BITCOIN_BROADCASTdefault false

Explicitly enable signed Bitcoin transaction broadcasts

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

evm_getBlockNumber

evm_getChainInfo

evm_getNativeBalance

evm_getBlock

evm_getTransaction

evm_call

evm_readContract

evm_estimateTransaction

evm_getLogs

evm_broadcastTransaction

btc_getBlockchainInfo

btc_getAddressBalance

btc_getBlock

btc_getTransaction

btc_getTxOut

btc_estimateFee

btc_decodeRawTransaction

btc_broadcastTransaction

ChainRPC MCP

JSON-RPC MCP server for EVM chains and Bitcoin

Choose how to connect

Hosted, read-only service

Local stdio server

Available tools

EVM

Bitcoin

Safety model

Configuration

Self-host with Streamable HTTP

Development

License

Install

Configuration

Related servers