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

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.github.Bortlesboat/bitcoin-mcp
• PyPI
• GitHub
• Full tool documentation

Examples

See the examples/ folder for documented usage patterns:

• Fee Analysis — find optimal send timing
• Mempool Monitor — track congestion
• Transaction Investigation — decode and analyze transactions
• Block Analysis — inspect and compare blocks

Support This Project

bitcoin-mcp is free, open-source Bitcoin infrastructure. Support development through GitHub Sponsors, reproducible issue reports, documentation improvements, and tested patches.

Contributing

Run the unit suite with python -m pytest tests/. For the optional Core/Knots checks over the MCP interface, see real-node integration tests.

Contributions are welcome. See CONTRIBUTING.md for guidelines, including how to add new tools and the PR checklist.

Please report security vulnerabilities privately — see SECURITY.md.

About

bitcoin-mcp is created and maintained by Andrew Barnes, bridging AI agents and Bitcoin infrastructure through the Model Context Protocol.

Related projects:

• Satoshi API — Bitcoin fee intelligence API, 108 endpoints, usable as a self-hosted compatible backend
• ChainPulse — AI-powered Bitcoin network intelligence CLI
• BAIP-1 — Bitcoin Agent Identity Protocol
• bitcoin-fee-observatory — Fee market analytics dashboard

License

MIT