Bitcoin MCP

bitcoin-mcp

Give any AI agent Bitcoin superpowers — fee intelligence, mempool analysis, and 50 tools backed by your Bitcoin node or compatible API.

50 standard tools · 6 prompts · 8 resources · Bitcoin Core or compatible API backend · MIT licensed

If bitcoin-mcp is useful to you, consider giving it a star — it helps others discover the project.

pip install "bitcoin-mcp>=0.5.2"

bitcoin-mcp needs a Bitcoin data backend. It auto-detects a local Bitcoin Core/Knots node from its cookie or RPC settings. Without a local node, set SATOSHI_API_URL to a compatible deployment.

Service status: the public Satoshi API previously hosted at bitcoinsapi.com is paused and should not be treated as a working default. Use a local node or an explicitly configured compatible API.

Install status

Version 0.5.2 includes the MCP SDK 1.x compatibility constraint and explicit backend selection. Upgrade older installations to receive these fixes.

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{

"mcpServers": { "bitcoin": { "command": "uvx", "args": ["--from", "bitcoin-mcp>=0.5.2", "bitcoin-mcp"] } } }

Claude Code

claude mcp add bitcoin -- uvx --from "bitcoin-mcp>=0.5.2" bitcoin-mcp

Cursor

Add to .cursor/mcp.json:

{

"mcpServers": { "bitcoin": { "command": "uvx", "args": ["--from", "bitcoin-mcp>=0.5.2", "bitcoin-mcp"] } } }

VS Code

Add to .vscode/mcp.json:

{

"servers": { "bitcoin": { "command": "uvx", "args": ["--from", "bitcoin-mcp>=0.5.2", "bitcoin-mcp"] } } }

Zed

Add to your Zed settings.json under context_servers:

{

"context_servers": { "bitcoin": { "command": "uvx", "args": ["--from", "bitcoin-mcp>=0.5.2", "bitcoin-mcp"] } } }

See the Zed MCP docs for the current settings location and custom server flow.

Docker

docker build -t bitcoin-mcp .

docker run -i bitcoin-mcp

Or with docker compose:

docker compose up

Pass environment variables to connect to a local Bitcoin Core node or a compatible API:

docker run -i -e BITCOIN_RPC_HOST=host.docker.internal -e BITCOIN_RPC_PORT=8332 bitcoin-mcp

or

docker run -i -e SATOSHI_API_URL=https://your-api.example bitcoin-mcp

Ask whether to send Bitcoin now

Use this as the first useful activation path after install:

"I need to send a Bitcoin transaction today. Use bitcoin-mcp to decide whether to send now or wait, and show the fee rate you used."

Expected path:

1. The agent calls get_fee_recommendation.
2. The answer gives a clear send now or wait recommendation with fee rates in sat/vB.
3. If the backend is unavailable, configure a local node or set SATOSHI_API_URL before retrying.

After it works, Star this repo and share a short showcase with the prompt, tool call, and outcome so other Bitcoin agent builders can see the path.

Agent Integration

For repos that need Bitcoin tools, add bitcoin-mcp to the agent's MCP config and configure one of its supported backends:

• Local Bitcoin Core/Knots RPC settings: BITCOIN_RPC_HOST, BITCOIN_RPC_PORT, and optional credentials or datadir
• Compatible remote API: SATOSHI_API_URL and, when required, SATOSHI_API_KEY
• Satoshi API source and integration reference: https://github.com/Bortlesboat/bitcoin-api/blob/master/docs/AGENT_INTEGRATION.md

Generated HTTP examples should use canonical Satoshi API /api/v1 paths.

Why bitcoin-mcp?

• Fee intelligence that saves real money — know the cheapest time to send, compare fee tiers, estimate exact costs before broadcasting
• Backend choice — use your own Bitcoin Core/Knots node or an explicitly configured compatible API
• Open source MCP tooling — tool definitions, tests, and client configuration examples are available in this repository

Top Use Cases

Ask your AI agent:

Full Tool Reference

All 50 standard tools by category

Fee Intelligence

Blocks & Transactions

Mempool

Mining

Network & Status

Address & UTXO

Indexed Address (requires blockchain indexer)

Security

Utility

Optional Remote API Tool

query_remote_api is registered only when SATOSHI_API_URL is set and the l402 extra is installed. It queries canonical /api/v1 routes on that explicitly configured endpoint.

Configuration

Configure either a local Bitcoin Core/Knots node or a compatible remote API. If neither is available, bitcoin-mcp exits its connection check with a setup error instead of silently selecting an unavailable public service.

CLI Flags

bitcoin-mcp supports the following runtime flags:

Example:

bitcoin-mcp --transport sse --host 127.0.0.1 --port 8000 --log-level DEBUG

To connect to a local Bitcoin Core node:

{

"mcpServers": { "bitcoin": { "command": "uvx", "args": ["--from", "bitcoin-mcp>=0.5.2", "bitcoin-mcp"], "env": { "BITCOIN_RPC_HOST": "127.0.0.1", "BITCOIN_RPC_PORT": "8332" } } } }

Prompts & Resources

6 built-in prompts for common workflows: analyze_fee_environment, investigate_transaction, monitor_mempool_fees, taproot_adoption_report, network_health_report, track_transaction

8 resources for context injection: bitcoin://connection/status, bitcoin://node/status, bitcoin://fees/current, bitcoin://fees/history, bitcoin://mempool/snapshot, bitcoin://protocol/script-opcodes, bitcoin://protocol/address-types, bitcoin://protocol/sighash-types

Links

• Satoshi API source — optional compatible backend implementation (public hosted service currently paused)
• MCP Registry — `io.gith