▶ Hackathon project
§ Project file

Bitcoin Kernel MCP

The permanent record for this hackathon project: write-up, links, team, tags, and prizes.
Third Place building consensus
Don't let your AI agent reason about Bitcoin consensus. Let it ask the consensus engine directly: an MCP server exposing libbitcoinkernel for hallucination-free script and block validation.
View code ↗
The write-up

bitcoin-kernel-mcp

Ask the consensus engine, not the model

LLMs are decent at talking about Bitcoin and terrible at executing its rules. Ask one whether a signature is valid or why a block got rejected and it will produce a confident answer that may or may not be true. Consensus has exact answers, and there‘s exactly one codebase that defines them.

bitcoin-kernel-mcp is an MCP server that puts that codebase in reach of any agent. It wraps libbitcoinkernel, the library that encapsulates Bitcoin’s consensus engine. When an agent needs to know whether a script spend is valid, it stops reasoning and runs the same C++ that validates every block on mainnet. The verdict comes back as structured JSON.

What agents can do with it

Verify any script spend. Full flag support, and every check also runs across the seven historical rule eras from 2009 to Taproot. A failing spend doesn‘t just fail, it tells you which soft fork killed it. Corrupt one byte of a taproot signature and the consensus engine reports: valid under SegWit rules, invalid once BIP341 activates. Pre-activation, that output was anyone-can-spend. Try getting that from a chat model.

Validate headers and blocks. Paste 80 bytes of header hex and the consensus engine re-checks the proof of work behind it. Paste a whole block and get the precise rejection reason: broken PoW, mutated transaction data, missing parent, timestamp too far in the future.

Run what-if experiments. Sandboxes are private regtest chains living entirely in memory. Mining 150 blocks takes under a second, and the server builds consensus-correct blocks around agent-supplied transactions. Double spends, inflation attempts, premature coinbase spends: each comes back with the engine’s verdict instead of a hand-wave. Coinbases pay to OP_TRUE, so building test transactions takes byte concatenation, not key management.

Read a real node‘s history. Point it at a node’s datadir and it loads the node‘s own block index. Undo data gives you what every input spent, which means fees and input scripts for any historical transaction with no txindex, no explorer, no RPC. The node doesn’t even need to be running.

Built for agents, not just callable by them

The server ships its own documentation as MCP resources: a decision table mapping questions to tools, a deep guide to verification flags, every block rejection reason explained, and a cookbook for building test scenarios. There‘s also a guide on the consensus/policy boundary, because the most common way to misuse consensus tooling is to mistake “valid in a block” for “will be relayed”, and an agent that reads it will stop making that mistake.

Practical details

17 tools, 35 tests, one-line install for Claude Code, Claude Desktop, or Cursor. Python with prebuilt wheels via py-bitcoinkernel, so there’s nothing to compile. MIT licensed.

claude mcp add bitcoin-kernel -- uvx bitcoin-kernel-mcp

The kernel API is still experimental upstream, and this is a research and tooling instrument, not something to wire into production money flows. For everything else: stop letting your agent guess about consensus. It can ask.