bitcoin-mcp 0.4.0

MCP server for Bitcoin Core/Knots nodes — 40 tools for AI agents to save money on fees

bitcoin-mcp

MCP server that lets AI agents save money on Bitcoin fees and save time monitoring payments. Your agent can check whether to send now or wait, verify when a payment confirms, and query any blockchain data — without you building custom Bitcoin plumbing.

Runs against your local node or the free hosted Satoshi API. No API keys needed, no rate limits, no third-party dependencies.

The first Bitcoin MCP server on the official Anthropic MCP Registry. 40 tools, 6 prompts, 7 resources.

60-Second Quickstart

# 1. Install
pip install bitcoin-mcp

# 2. No node needed — use the hosted API:
SATOSHI_API_URL=https://bitcoinsapi.com bitcoin-mcp

# 3. Verify it works:
bitcoin-mcp --check

# 4. Add to Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp",
      "env": { "SATOSHI_API_URL": "https://bitcoinsapi.com" }
    }
  }
}

# 5. Ask Claude: "Give me a Bitcoin briefing"

That's it. No local node required.

Advanced: Use Your Own Node

If you run Bitcoin Core or Bitcoin Knots locally, the server auto-detects it via cookie authentication:

bitcoin-mcp              # auto-detects local node
bitcoin-mcp --check      # verify connection

Install

pip install bitcoin-mcp

Configuration

Override with environment variables if needed:

SATOSHI_API_URL=https://bitcoinsapi.com  # use hosted API (no local node needed)
BITCOIN_RPC_HOST=127.0.0.1              # local node host
BITCOIN_RPC_PORT=8332                    # local node port
BITCOIN_RPC_USER=myuser
BITCOIN_RPC_PASSWORD=mypassword
BITCOIN_DATADIR=E:/
BITCOIN_NETWORK=mainnet                  # mainnet (default) | testnet | signet | regtest

Recipes

Copy-paste these into Claude Desktop or Claude Code with bitcoin-mcp installed. Each one saves you money or time.

"Give me a Bitcoin briefing"

Give me a 30-second Bitcoin briefing: current price, fees, mempool congestion, and whether it's a good time to send.

Uses get_situation_summary. Returns BTC price, fee rates at 3 urgency levels, typical transaction cost in USD, and mempool state — all in one call.

"How much will my transaction cost in dollars?"

I want to send Bitcoin from 2 inputs to 2 outputs, all native SegWit. How much will the fee be in dollars at each urgency level?

Uses estimate_transaction_cost. Calculates exact vsize for your transaction shape, multiplies by current fee rates, converts to USD. Shows how much you save by waiting.

"Should I send Bitcoin right now?"

What's the current fee environment? Should I send a transaction now or wait for lower fees? How much would I save by waiting?

Uses get_fee_recommendation + analyze_mempool + compare_fee_estimates. Returns plain-English advice with specific sat/vB rates and estimated savings.

"Did I overpay on this transaction?"

Analyze transaction <txid> and tell me if I overpaid on the fee. What's the current rate for the same priority? Show the difference in dollars.

Uses analyze_transaction + compare_fee_estimates + get_btc_price. Retroactive fee audit — shows exactly how much you could have saved.

"Track this payment"

Track this transaction and tell me when it's safe to consider confirmed: <txid>

Uses analyze_transaction + mempool tools. Reports confirmation count, fee rate paid, whether it's likely to confirm in the next block, and RBF status.

"What fee should I set for a 2-input, 1-output Taproot transaction?"

I'm building a transaction with 2 P2TR inputs and 1 P2TR output. What fee should I set for confirmation within 3 blocks?

The agent calculates exact vsize for your transaction shape, then checks current fee rates to give you a precise sat amount — not a guess.

"Decode this transaction"

Decode and explain this transaction: <txid>

Full breakdown: inputs, outputs, fee rate, SegWit/Taproot flags, inscription detection, script types. Plain English, not raw hex.

"What's happening in the mempool right now?"

Analyze the current mempool. How congested is it? What's the fee distribution? How many transactions are waiting?

Returns congestion level (low/medium/high), fee bucket breakdown, next-block minimum fee, and total pending transaction count.

"How much Bitcoin exists right now?"

What's the current Bitcoin supply? When is the next halving? What's the inflation rate compared to the Fed's target?

Uses get_supply_info. Returns circulating supply, percentage mined, halving countdown, and annual inflation rate — all derived from live node data.

"Is my node healthy?"

Run a full health check on my Bitcoin node. Check sync status, peer connections, and network health.

Comprehensive report: sync progress, peer count and quality, protocol version, disk usage, mempool state, difficulty adjustment progress.

"When is the cheapest time to send?"

Look at fee history for the last 24 hours. When were fees lowest? Is there a pattern?

Historical fee analysis showing the cheapest window, peak fees, and current position relative to the range.

"What will the next block look like?"

Analyze the current block template. What transactions are likely to be included? What's the minimum fee to get in?

Shows the projected next block: transaction count, total fees, fee percentiles, and the top-paying transactions waiting to confirm.

"Compare urgency levels"

Compare fee rates for different urgency levels. How much more does next-block confirmation cost vs. waiting an hour? Show me in dollars.

Side-by-side comparison: next block vs. ~1 hour vs. ~1 day. Shows exact cost in sats and USD for your specific transaction shape.

"When is the next halving?"

How many blocks until the next Bitcoin halving? What will the new block reward be?

Uses get_halving_countdown. Returns blocks remaining, estimated days, and the subsidy change — based on actual block production rate, not the assumed 10-minute average.

"Monitor for whale transactions"

Watch the mempool for any transaction moving more than 10 BTC.

Real-time whale alert: streams large transactions as they enter the mempool with value, fee rate, and size.

"What's the current Bitcoin price?"

What's the BTC/USD price right now? How has it changed in the last 24 hours?

Uses get_btc_price. Returns price, 24h change, and market cap from CoinGecko — no API key needed.

---

40 Tools

Node & Network (3)

Tool	Description
get_node_status	Chain, height, sync progress, disk, connections, version
get_peer_info	Connected peer addresses, latency, services
get_network_info	Protocol version, relay fee, warnings

Blockchain & Blocks (6)

Tool	Description
analyze_block	Full analysis: pool ID, SegWit/Taproot adoption, fee distribution
get_blockchain_info	Chain, difficulty, softforks, chain work
get_block_stats	Raw statistics: median fee, total output, subsidy
get_chain_tx_stats	Transaction rate over N blocks
get_chain_tips	Active chain, forks, and stale branches
search_blocks	Block stats for a range of heights (max 10)

Mempool (4)

Tool	Description
analyze_mempool	Fee buckets, congestion level, next-block minimum fee
get_mempool_entry	Details of a specific unconfirmed tx
get_mempool_info	Quick stats: count, bytes, min relay fee
get_mempool_ancestors	Ancestor transactions for CPFP analysis

Transactions (4)

Tool	Description
analyze_transaction	Full decode + inscription detection + fee analysis
decode_raw_transaction	Decode raw hex without input lookup
send_raw_transaction	Broadcast a signed transaction (with fee safety limit)
check_utxo	Check if a specific output is unspent

Fee Estimation (5)

Tool	Description
get_fee_estimates	Rates for 1/3/6/25/144 block targets
get_fee_recommendation	Plain-English send/wait advice with raw rate data
estimate_smart_fee	Custom confirmation target
compare_fee_estimates	Side-by-side urgency labels + cost for 140vB tx
estimate_transaction_cost	Cost in sats AND USD by address type, inputs, outputs — with savings from waiting

Mining (2)

Tool	Description
get_mining_info	Difficulty, hashrate, block size
analyze_next_block	Block template: revenue, fee percentiles, top-fee txs

UTXO Set (2)

Tool	Description
get_utxo_set_info	Total UTXOs, supply, disk size (slow: ~1-2 min)
get_block_count	Current block height (fast)

Price & Supply (3)

Tool	Description
get_btc_price	BTC/USD price, 24h change, market cap (CoinGecko, no API key)
get_supply_info	Circulating supply, inflation rate, halving countdown from live node
get_halving_countdown	Focused countdown: blocks remaining, estimated date, subsidy change

AI Developer Tools (10)

Tool	Description
get_situation_summary	One-call briefing: price + fees + mempool + chain tip + typical tx cost in USD
describe_rpc_command	Structured help for any RPC command
list_rpc_commands	All commands grouped by category
search_blockchain	Smart router: auto-detects txid, block hash/height, or address
explain_script	Decode script hex into readable opcodes
get_address_utxos	Scan UTXO set for an address
validate_address	Validate and classify address type (P2PKH/P2SH/P2WPKH/P2WSH/P2TR)
get_difficulty_adjustment	Epoch progress, estimated adjustment percentage
compare_blocks	Side-by-side block statistics comparison

Lightning (1)

Tool	Description
decode_bolt11_invoice	Decode a BOLT11 Lightning invoice (no LN node needed)

6 Agent Workflow Prompts

Pre-built multi-step analysis templates that agents can invoke:

Prompt	Description
analyze_fee_environment	Fee market analysis with send/wait recommendation
investigate_transaction	Deep-dive transaction investigation
monitor_mempool_fees	Watch for fee drops below threshold
taproot_adoption_report	P2TR adoption trends over recent blocks
network_health_report	Comprehensive network health assessment
track_transaction	Track a tx from mempool to confirmation

7 Resources

Static data endpoints for AI agents:

• bitcoin://node/status — node summary
• bitcoin://fees/current — fee estimates
• bitcoin://mempool/snapshot — mempool analysis
• bitcoin://connection/status — connection status + troubleshooting hints
• bitcoin://protocol/script-opcodes — Bitcoin Script opcodes reference
• bitcoin://protocol/address-types — address type properties and BIPs
• bitcoin://protocol/sighash-types — signature hash types

Example Configs

See examples/ for ready-to-use config snippets:

• Claude Desktop
• Claude Code
• Cursor
• Windsurf

What Makes This Different

Feature	bitcoin-mcp	Competitors
Official MCP Registry	Yes	No
Tools / Prompts / Resources	40 / 6 / 7	Fewer
Fee estimates in USD	Yes (live BTC price)	No
"Should I send now?"	Yes (saves you money)	No
Data source	Your local node	Third-party APIs
No-node fallback	Satoshi API remote	N/A
Mempool analysis	Fee bucketing, congestion, CPFP	Basic stats only
Inscription detection	Yes	No
Pool identification	Yes	No
SegWit/Taproot metrics	Yes	No
Next-block prediction	Yes	No
Supply & halving data	Yes	No
Agent workflow prompts	6 built-in	None
Rate limits	None	API-dependent

CLI

bitcoin-mcp              # Start MCP server (default)
bitcoin-mcp --version    # Print version
bitcoin-mcp --check      # Test RPC connection and exit

Requirements

• Python 3.10+
• Bitcoin Core or Bitcoin Knots with server=1 in bitcoin.conf
• txindex=1 recommended for transaction lookups

Related

• Satoshi API — REST API for Bitcoin nodes (pairs with bitcoin-mcp for remote access)
• bitcoinlib-rpc — the Python library powering this server
• Bitcoin Protocol Guide — educational companion

License

MIT