chain-reader — Read-only Ethereum MCP server

An MCP server that lets an LLM read Ethereum in natural language. It holds no private keys, signs nothing, and sends nothing. Every result comes with "where that answer came from."

Written as a working teaching prototype of the diagram in the final chapter "Blockchain and AI" of Tim Weingärtner (HSLU)'s Ethereum & Smart Contracts.

  LLM         ← 自然言語（「このアドレスは何者？」）
   ↓
  MCP         ← src/server.js
   ↓          ← コード／構造化言語（ABI エンコード）
  RPC         ← src/rpc.js
   ↓
ブロックチェーン

The only dependencies are @modelcontextprotocol/sdk and zod. The Keccak-256 and the ABI encoder are both hand-written (see "Why I wrote it by hand" below).

Running it

git clone <this repo> && cd chain-reader-mcp
npm ci --ignore-scripts
npm test        # 単体 13 件（ネットワーク不要）
npm run smoke   # 実チェーンに対して全ツールを 1 回ずつ

Register it with Claude Code.

claude mcp add chain-reader -- node "$PWD/src/server.js"

If you launch claude from this directory, the .mcp.json is already there, so no registration is needed. However, approval is requested the first time only (claude mcp list will show ⏸ Pending approval). To avoid scrambling on the day of the lecture, launch it once beforehand and approve it.

For Claude Desktop, write the same content in the mcpServers section of claude_desktop_config.json. In that case, make args an absolute path.

The target network can be switched with environment variables. The default is mainnet.

Both use public endpoints that require no API key. local looks at http://127.0.0.1:8545 from anvil / hardhat node.

Tools and their correspondence to the lecture

The lecture slides themselves live in a separate repository (a private Japanese translation), but listing the section names should be enough to trace the correspondence.

Selecting the lecture_walkthrough prompt inserts instructions to walk through items 1–6 in order.

Questions you can use directly in the lecture

このネットワークはいま混んでいますか？
0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 は EOA ですか、コントラクトですか？
USDC の総供給量は？ その数字は誰が保証していますか？
transfer(address,uint256) のセレクタはなぜ 0xa9059cbb になるのですか？
私のアドレスから 0.001 ETH を送る取引を組み立ててください

For the last question, the AI returns the assembled JSON but cannot send it. Having it explain "why it cannot send it" makes the content of the slide "Cautions when using MCP" come out of the AI's own mouth.

Two design commitments

1. No keys

ALLOWED_METHODS in src/rpc.js is an explicit whitelist of read-only methods. eth_sendRawTransaction / eth_sendTransaction / eth_sign are not in it, and calling them fails before anything reaches the network (pinned down by unit tests).

Neither a signing implementation nor private-key loading exists anywhere in this repository. No matter how the LLM is steered, no funds can move from here.

prepare_unsigned_transaction exists to show this boundary as something that works, not as "something you can't do." It returns a finished transaction with the nonce, gas estimate, and fee all filled in, leaving only the signature to the human. The lecture slide's "An MCP can safely do only two things: read-only calls and relaying signed transactions" is implemented exactly as stated.

2. Never throw away where an answer came from

Every result carries _provenance.

"_provenance": {
  "endpoint": "https://ethereum-rpc.publicnode.com",
  "network": "mainnet (Ethereum Mainnet)",
  "rpc_calls": ["eth_blockNumber (1309ms)", "eth_gasPrice (1416ms)", "eth_chainId (1769ms)", "eth_getBlockByNumber (1023ms)"],
  "note": "これは単一の RPC エンドポイントの応答であり、独立に検証したものではない。"
}

This is a mechanism to keep from stopping at "it's a blockchain, so it's correct." LLMs have a habit of stating numbers with total confidence, so the result itself carries which claim stands on which layer. The server's instructions also direct the model to distinguish between facts guaranteed by the chain and content someone has self-reported.

Being attributable and being verifiable are different things

This server's output design comes from the context of records management and digital archives. The difference between what can be said and whether it is true is embedded in the tool outputs.

read_token's self_reported_note — the fact that name() returned "USD Coin" is guaranteed by the chain. But it does not guarantee that the contract is really Circle's. Anyone can deploy a contract with the same name and symbol. What the chain guarantees is only "the code at this address answered this way," not the truth of that claim.

verify_anchor's what_this_does_not_prove — what anchoring provides is "when, who, and what was claimed," not "whether the claim is correct." A hash of a wrong measurement can be anchored just as easily as a hash of a correct one. The diplomatics distinction that authenticity is not truth comes out exactly as is.

_provenance — a minimal implementation of the idea that the quality of a record is the shape of its provenance graph. Which endpoint answered, via which RPC call, in how many milliseconds. It leaves open the decision of who to make the prov:wasAttributedTo in PROV-O terms.

Layering on signed attestations / cross-checking against public information / TEE attestation / institutional authentication increases the strength of verification, but no matter how far you go, "the measuring instrument itself" cannot be verified. What this prototype demonstrates is the bottom layer of that stack — the realm where attribution is possible but verification is not. That is precisely why the record itself must note which layer a number stands on.

Why I wrote Keccak and ABI by hand

Installing viem or ethers would have done it in three lines. There are two reasons I deliberately didn't.

1. Because it's lecture material. If the ABI stays magic, you can't explain "why 4 bytes." src/keccak.js and src/abi.js together are about 300 lines, short enough for students to read through.

2. Because it keeps dependencies down to two. The smaller the supply-chain surface, the higher the odds that npm ci still works three years from now.

Node's crypto provides sha3-256, which is NIST SHA-3, and its padding differs from Ethereum's Keccak-256 (0x06 vs. 0x01), so it can't be reused. This one had to be implemented.

The supported range is address / uintN / intN / bool / bytesN / string / bytes and their dynamic arrays. Tuples and nested dynamic arrays are not handled. That's sufficient for a prototype, but if you're going to deal with arbitrary contracts in production, replace it with viem.

Known limitations

• It trusts a single RPC. Sending the same query to multiple endpoints and cross-checking would add one layer of trust. Not implemented.

• It cannot handle tuple types. Return values like Uniswap V3's slot0() cannot be decoded.

• read_events scans 200 blocks by default. Public endpoints may reject broad eth_getLogs queries.

• verify_anchor searches by substring match. If the anchor contract's ABI is known, it should decode the arguments properly and match against them.

• Everything except the local network depends on public endpoints. To be safe against an outage on the day of the lecture, fork locally with anvil --fork-url.

File structure

src/keccak.js   Keccak-256（既知ベクタで固定）
src/abi.js      ABI エンコード／デコード
src/rpc.js      JSON-RPC クライアント + 読み取り専用ホワイトリスト
src/tools.js    ツール 10 個の実体。MCP から独立していて単体で呼べる
src/server.js   MCP サーバ（stdio）
test/unit.test.js      ネットワーク不要の単体テスト
test/smoke.mjs         実チェーンに対する疎通確認
test/mcp-handshake.mjs MCP プロトコルの往復確認