{ "markdown": "# ChainRPC MCP\n\n#### JSON-RPC MCP server for EVM chains and Bitcoin\n\n\n\n[![npm](https://img.shields.io/npm/v/chainrpc-mcp?logo=npm)](https://www.npmjs.com/package/chainrpc-mcp)\n[![CI](https://github.com/John0n1/chainrpc-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/John0n1/chainrpc-mcp/actions/workflows/ci.yml)\n[![Node.js](https://img.shields.io/node/v/chainrpc-mcp)](package.json)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nA safety-first [Model Context Protocol](https://modelcontextprotocol.io/) server for EVM chains and Bitcoin.\n\nChainRPC 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.\n\n- **Two ecosystems, one server:** EVM JSON-RPC and Bitcoin Core-compatible RPC.\n- **Useful without an account:** defaults to public Ethereum and Bitcoin endpoints from [PublicNode](https://publicnode.com/).\n- **Bring your own infrastructure:** replace either endpoint and optionally use HTTP Basic authentication.\n- **Official transports:** local stdio and stateful Streamable HTTP through the official MCP SDK.\n- **Constrained by design:** no arbitrary RPC passthrough and no wallet, admin, debug, miner, or node-management methods.\n\n## Choose how to connect\n\n### Hosted, read-only service\n\nThe public endpoint is available now:\n\n```text\nhttps://chainrpc-mcp.mitander.io/mcp\n```\n\nFor clients that accept a remote Streamable HTTP server:\n\n```json\n{\n \"mcpServers\": {\n \"chainrpc-mcp\": {\n \"url\": \"https://chainrpc-mcp.mitander.io/mcp\"\n }\n }\n}\n```\n\nHealth and upstream status:\n\n```sh\ncurl 'https://chainrpc-mcp.mitander.io/health?upstream=1'\n```\n\nThe 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.\n\n### Local stdio server\n\nRequirements: Node.js 20 or newer.\n\n```sh\nnpx -y chainrpc-mcp\n```\n\nExample client configuration:\n\n```json\n{\n \"mcpServers\": {\n \"chainrpc-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"chainrpc-mcp\"],\n \"env\": {\n \"EVM_RPC_URL\": \"https://ethereum-rpc.publicnode.com\",\n \"BITCOIN_RPC_URL\": \"https://bitcoin-rpc.publicnode.com\"\n }\n }\n }\n}\n```\n\nThe RPC variables are optional; they are shown to make the defaults explicit.\n\n## Available tools\n\n### EVM\n\n| Tool | Purpose | State-changing |\n|---|---|---:|\n| `evm_getBlockNumber` | Return the latest block number | No |\n| `evm_getChainInfo` | Return chain ID and client version | No |\n| `evm_getNativeBalance` | Read a native-token balance at a block | No |\n| `evm_getBlock` | Read a block by number, tag, or hash | No |\n| `evm_getTransaction` | Read a transaction and receipt | No |\n| `evm_call` | Execute an `eth_call` with encoded calldata | No |\n| `evm_readContract` | Encode, call, and decode a function from its ABI | No |\n| `evm_estimateTransaction` | Estimate gas for an unsigned transaction | No |\n| `evm_getLogs` | Query event logs with address and topic filters | No |\n| `evm_broadcastTransaction` | Preflight and submit signed transaction bytes | **Yes** |\n\nAny 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.\n\n### Bitcoin\n\n| Tool | Purpose | State-changing |\n|---|---|---:|\n| `btc_getBlockchainInfo` | Return network, height, sync, and pruning information | No |\n| `btc_getAddressBalance` | Scan confirmed UTXOs for an address | No |\n| `btc_getBlock` | Read a block by height or hash | No |\n| `btc_getTransaction` | Read raw transaction details | No |\n| `btc_getTxOut` | Look up an unspent transaction output | No |\n| `btc_estimateFee` | Estimate a fee rate for a confirmation target | No |\n| `btc_decodeRawTransaction` | Decode serialized transaction bytes | No |\n| `btc_broadcastTransaction` | Validate and submit signed transaction bytes | **Yes** |\n\nBitcoin 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.\n\n## Safety model\n\nChainRPC MCP treats transaction submission as an exceptional operation:\n\n- Broadcasting is off unless `ALLOW_EVM_BROADCAST` or `ALLOW_BITCOIN_BROADCAST` is explicitly enabled.\n- The server accepts only serialized, already-signed transaction bytes.\n- Every broadcast call requires the literal confirmation `I understand this broadcasts a real transaction`.\n- EVM submission checks the endpoint and transaction chain IDs, rejects unprotected legacy transactions, recovers the signer, and runs `eth_estimateGas` first.\n- Bitcoin submission checks the endpoint network and requires `testmempoolaccept` to approve the transaction.\n- Submission requests are never automatically retried. A timeout can leave broadcast status ambiguous.\n- Read inputs use strict schemas; upstream concurrency, timeout, retry, and response sizes are bounded.\n- HTTP mode validates hosts and browser origins, supports bearer authentication, caps request bodies, and binds to loopback by default.\n\nRPC 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.\n\nSee [SECURITY.md](SECURITY.md) for vulnerability reporting and the complete trust boundary.\n\n## Configuration\n\nCopy [`example.env`](example.env) to `.env` when running from a checkout.\n\n| Variable | Default | Description |\n|---|---|---|\n| `EVM_RPC_URL` | `https://ethereum-rpc.publicnode.com` | Any HTTP(S) EVM JSON-RPC endpoint |\n| `BITCOIN_RPC_URL` | `https://bitcoin-rpc.publicnode.com` | Any HTTP(S) Bitcoin Core-compatible endpoint |\n| `EVM_RPC_USERNAME` / `EVM_RPC_PASSWORD` | unset | Optional EVM HTTP Basic authentication pair |\n| `BITCOIN_RPC_USERNAME` / `BITCOIN_RPC_PASSWORD` | unset | Optional Bitcoin HTTP Basic authentication pair |\n| `RPC_TIMEOUT_MS` | `12000` | Per-attempt upstream timeout |\n| `RPC_RETRIES` | `1` | Retry count for retryable reads only |\n| `RPC_MAX_RESPONSE_BYTES` | `10000000` | Maximum upstream response body |\n| `RPC_MAX_CONCURRENCY` | `20` | Maximum concurrent requests per chain client |\n| `ALLOW_EVM_BROADCAST` | `false` | Enable signed EVM transaction submission |\n| `ALLOW_BITCOIN_BROADCAST` | `false` | Enable signed Bitcoin transaction submission |\n| `TRANSPORT` | `stdio` | Default transport: `stdio` or `http` |\n| `HOST` / `PORT` | `127.0.0.1` / `3000` | HTTP bind address and port |\n| `MCP_PATH` | `/mcp` | Streamable HTTP MCP path |\n| `MCP_AUTH_TOKEN` | unset | Optional bearer token for `/mcp` |\n| `ALLOWED_HOSTS` | unset | Required allowlist when binding HTTP to a non-loopback address |\n| `CORS_ORIGINS` | unset | Comma-separated browser-origin allowlist |\n| `MAX_MCP_SESSIONS` | `1000` | Maximum concurrent HTTP MCP sessions |\n| `HTTP_BODY_LIMIT` | `1mb` | Express request-body limit |\n\n`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.\n\n## Self-host with Streamable HTTP\n\nStart a loopback-only HTTP server:\n\n```sh\nnpm start\ncurl 'http://127.0.0.1:3000/health?upstream=1'\n```\n\nTo bind beyond loopback, explicitly set the host allowlist and authentication:\n\n```sh\nHOST=0.0.0.0 \\\nALLOWED_HOSTS=mcp.example.com \\\nMCP_AUTH_TOKEN='replace-with-a-long-random-secret' \\\nnpm start\n```\n\nTerminate 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.\n\nDocker defaults to stdio. Override the command for HTTP:\n\n```sh\ndocker build -t chainrpc-mcp .\ndocker run --rm -p 127.0.0.1:3000:3000 \\\n -e HOST=0.0.0.0 \\\n -e ALLOWED_HOSTS=localhost,127.0.0.1 \\\n -e MCP_AUTH_TOKEN='replace-with-a-long-random-secret' \\\n chainrpc-mcp --http\n```\n\nProduction service topology:\n\n```text\nMCP client\n |\n v\nCloudflare edge -> outbound-only Cloudflare Tunnel -> nginx on loopback\n |\n v\n ChainRPC MCP\n / \\\n v v\n EVM RPC Bitcoin RPC\n```\n\nDeployment units, nginx configuration, hardening details, and operating commands are in [docs/OPERATIONS.md](docs/OPERATIONS.md).\n\n## Development\n\n```sh\ngit clone https://github.com/John0n1/chainrpc-mcp.git\ncd chainrpc-mcp\nnpm ci\nnpm run check\nnpm run test:coverage\n```\n\nUseful commands:\n\n| Command | Purpose |\n|---|---|\n| `npm run start:stdio` | Start the stdio transport |\n| `npm start` | Start Streamable HTTP |\n| `npm run dev` | Start HTTP with Node watch mode |\n| `npm test` | Run the test suite |\n| `npm run check` | Syntax-check the entry point and run all tests |\n| `npm pack --dry-run` | Inspect the npm package contents |\n\nThe detailed design and remediation record is in [docs/AUDIT.md](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.\n\n## License\n\n[MIT](LICENSE)\n", "bytes": 10031, "sha": "09788e3c97ca5f97496919a6059ce7763c5e658dc94cfdf515bf54b1e74c7742", "repo_slug": "john0n1/chainrpc-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_john0n1_chainrpc_mcp_f1f1a70c/readme" }