bitcoin-mcp

bitcoin-mcp

<!-- mcp-name: io.github.Bortlesboat/bitcoin-mcp -->

Give any AI agent Bitcoin superpowers — fee intelligence, mempool analysis, and 49 tools. Zero config, one command.

      

49 tools · 126 tests · 6 prompts · 8 resources · Zero config · MIT licensed

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

pip install bitcoin-mcp

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bitcoin": {
      "command": "uvx",
      "args": ["bitcoin-mcp"]
    }
  }
}

Claude Code

claude mcp add bitcoin -- uvx bitcoin-mcp

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "bitcoin": {
      "command": "uvx",
      "args": ["bitcoin-mcp"]
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "bitcoin": {
      "command": "uvx",
      "args": ["bitcoin-mcp"]
    }
  }
}

Zed

Add to your Zed settings.json under context_servers:

{
  "context_servers": {
    "bitcoin": {
      "command": "uvx",
      "args": ["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 set your API key:

docker run -i -e SATOSHI_API_KEY=your-key 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 you will repeat this check, register a free Satoshi API key and add SATOSHI_API_KEY to your MCP config.
4. If you need a one-off paid API call instead of the MCP tool, use https://bitcoinsapi.com/x402/start.

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 link the Satoshi API integration kit:

• Satoshi API agent guide: https://github.com/Bortlesboat/bitcoin-api/blob/main/docs/AGENT_INTEGRATION.md
• Agent-readable overview: https://bitcoinsapi.com/llms.txt
• MCP setup: https://bitcoinsapi.com/mcp-setup
• x402 first paid call: https://bitcoinsapi.com/x402/start

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
• Zero config — works instantly with the free hosted Satoshi API, or connect your own Bitcoin Core node
• First Bitcoin MCP server on the Anthropic Registry

Top Use Cases

Ask your AI agent:

| Prompt | What it does | |--------|-------------| | "What's the cheapest time to send Bitcoin today?" | Fee recommendation with savings breakdown | | "Analyze the current mempool congestion" | Real-time mempool depth, fee tiers, pending tx count | | "How much would I save waiting 6 blocks vs next block?" | Side-by-side fee comparison across confirmation targets | | "Search for this transaction: abc123..." | Full transaction decode with inscription detection | | "Give me a situation summary of Bitcoin right now" | Price, fees, mempool, mining, difficulty — one call |

Full Tool Reference

<details> <summary>All 49 tools by category</summary>

Fee Intelligence

| Tool | Description | |------|-------------| | get_fee_recommendation | Optimal fee rate with urgency tiers and savings tips | | get_fee_estimates | Fee estimates across all confirmation targets | | estimate_smart_fee | Fee estimate for a specific confirmation target | | compare_fee_estimates | Side-by-side comparison of fee sources | | estimate_transaction_cost | Exact cost estimate for a transaction before sending |

Blocks & Transactions

| Tool | Description | |------|-------------| | analyze_block | Deep analysis of any block by height or hash | | get_block_stats | Statistical breakdown of a block | | get_block_count | Current chain height | | compare_blocks | Compare two blocks side by side | | search_blocks | Search a range of blocks | | analyze_transaction | Full transaction analysis with inscription detection | | decode_raw_transaction | Decode a raw transaction hex | | send_raw_transaction | Broadcast a signed transaction | | check_utxo | Check if a UTXO is spent or unspent |

Mempool

| Tool | Description | |------|-------------| | analyze_mempool | Full mempool analysis — depth, fees, congestion | | get_mempool_info | Mempool size, bytes, fee floor | | get_mempool_entry | Details for a specific unconfirmed transaction | | get_mempool_ancestors | Ancestor chain for a mempool transaction |

Mining

| Tool | Description | |------|-------------| | get_mining_info | Current mining difficulty, hashrate, block reward | | analyze_next_block | Preview of the next block template | | get_mining_pool_rankings | Top mining pools by recent blocks | | get_difficulty_adjustment | Time and percentage of next difficulty change | | get_halving_countdown | Blocks and estimated time until next halving |

Network & Status

| Tool | Description | |------|-------------| | get_blockchain_info | Chain state, verification progress, softfork status | | get_network_info | Node version, connections, relay info | | get_node_status | Connection status and node health | | get_peer_info | Connected peer details | | get_chain_tips | Active and stale chain tips | | get_chain_tx_stats | Transaction throughput over N blocks | | get_utxo_set_info | UTXO set size and total supply | | get_supply_info | Circulating supply, inflation rate, percent mined | | get_situation_summary | Aggregated overview — price, fees, mempool, mining | | get_btc_price | Current BTC/USD price | | get_market_sentiment | Fear/greed index and market indicators |

Address & UTXO

| Tool | Description | |------|-------------| | get_address_utxos | UTXOs for an address | | validate_address | Validate and classify a Bitcoin address |

Indexed Address (requires blockchain indexer)

| Tool | Description | |------|-------------| | get_address_balance | Total received/sent/balance, tx count, first/last seen | | get_address_history | Paginated transaction history with net value change | | get_indexed_transaction | Enriched tx with resolved input addresses + spent status | | get_indexer_status | Sync progress, ETA, blocks/sec |

Security

| Tool | Description | |------|-------------| | analyze_psbt_security | Security analysis of a Partially Signed Bitcoin Transaction | | explain_inscription_listing_security | Security guide for ordinal inscription listings |

Utility

| Tool | Description | |------|-------------| | search_blockchain | Universal search — address, txid, block hash, or height | | generate_keypair | Generate a new Bitcoin keypair | | explain_script | Decode and explain a Bitcoin script | | decode_bolt11_invoice | Decode a Lightning Network BOLT11 invoice | | describe_rpc_command | Help text for any Bitcoin Core RPC command | | list_rpc_commands | List all available RPC commands | | query_remote_api | Query the Satoshi API directly |

</details>

Get More Requests (Free)

bitcoin-mcp works immediately with 1,000 requests/day (anonymous). Register for a free API key to get 10,000/day (10x):

1. Visit bitcoinsapi.com
2. Register for a free key (takes 10 seconds)
3. Set the SATOSHI_API_KEY environment variable in your MCP config

Configuration

All environment variables are optional. bitcoin-mcp falls back to the free hosted Satoshi API when no local node is configured.

CLI Flags

bitcoin-mcp supports the following runtime flags:

| Flag | Values | Default | Description | |------|--------|---------|-------------| | --transport | stdio, sse, streamable-http | stdio | MCP transport to run | | --host | hostname / IP | 127.0.0.1 for HTTP transports | Bind host for sse and streamable-http | | --port | integer | 8000 for HTTP transports | Bind port for sse and streamable-http | | --log-level | DEBUG, INFO, WARNING, ERROR | INFO | Server log verbosity |

Example:

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

| Variable | Description | Default | |----------|-------------|---------| | BITCOIN_RPC_HOST | Bitcoin Core RPC host | 127.0.0.1 | | BITCOIN_RPC_PORT | Bitcoin Core RPC port | Auto by network | | BITCOIN_NETWORK | mainnet, testnet, signet, or regtest | mainnet | | SATOSHI_API_URL | Override hosted API URL | https://bitcoinsapi.com | | SATOSHI_API_KEY | API key for authenticated access | None |

To connect to a local Bitcoin Core node:

{
  "mcpServers": {
    "bitcoin": {
      "command": "uvx",
      "args": ["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 — the hosted backend powering zero-config mode
• Anthropic 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 OpenSats.

Contributing

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. It is the most comprehensive Bitcoin MCP server available, bridging AI agents and Bitcoin infrastructure through the Model Context Protocol.

Related projects:

• Satoshi API — Bitcoin fee intelligence API, 108 endpoints (powers zero-config mode)
• ChainPulse — AI-powered Bitcoin network intelligence CLI
• BAIP-1 — Bitcoin Agent Identity Protocol
• bitcoin-fee-observatory — Fee market analytics dashboard

License

MIT