Skip to main content
Glama

bitcoin-mcp

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

PyPI Downloads Tests License: MIT Python 3.10+ GitHub Sponsors

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.

Related MCP server: coin-mcp-server

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:

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:

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

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_address_transactions

Transaction history with per-transaction value details

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

decode_xpub

Decode and inspect an extended public key

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:

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

Compatible Satoshi API base URL

None

SATOSHI_API_KEY

API key for authenticated access

None

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

Examples

See the examples/ folder for documented usage patterns:

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

Available Tools

50 tools
analyze_blockB

Analyze a block: mining pool, SegWit/Taproot adoption, fee distribution, revenue.

Args: height_or_hash: Block height (e.g. "939290") or block hash

Inputs: height_or_hash (required). Returns: result

analyze_mempoolB

Analyze the mempool: tx count, fee buckets, congestion level, next-block minimum fee.

Inputs: no named parameters. Returns: result

analyze_next_blockB

Predict next block: transactions, weight utilization, miner revenue, fee percentiles, top-fee txs.

Inputs: no named parameters. Returns: result

analyze_psbt_securityA

Analyze a PSBT for ordinals inscription listing mempool sniping vulnerability.

Detects whether an ordinals listing PSBT is vulnerable to front-running in the mempool. A listing is VULNERABLE when it uses SIGHASH_SINGLE|ANYONECANPAY without a 2-of-2 multisig locking step — an attacker can redirect the inscription before confirmation. A listing is PROTECTED when the inscription is locked in a 2-of-2 P2WSH multisig and the marketplace co-signs with SIGHASH_ALL, preventing any transaction modification.

No Bitcoin node required — analysis is pure PSBT parsing (BIP 174).

Args: psbt_hex: Hex-encoded PSBT string (BIP 174 v0)

Inputs: psbt_hex (required). Returns: result

analyze_transactionA

Decode and analyze a transaction: inputs, outputs, fee rate, SegWit/Taproot flags, inscription detection.

Args: txid: Transaction hash (64 hex characters). Local nodes need txindex=1 for confirmed txs; the hosted API handles this automatically.

Inputs: txid (required). Returns: result

check_utxoA

Check if a specific transaction output is unspent (UTXO lookup).

Args: txid: Transaction hash vout: Output index

Inputs: txid (required), vout (required). Returns: result

compare_blocksC

Compare block statistics between two block heights side by side.

Args: height1: First block height height2: Second block height

Inputs: height1 (required), height2 (required). Returns: result

compare_fee_estimatesB

Compare fee estimates side-by-side with urgency labels and cost for a typical 140 vB transaction.

Inputs: no named parameters. Returns: result

decode_bolt11_invoiceA

Decode a BOLT11 Lightning invoice without external dependencies.

Parses the human-readable part to extract network, amount, and timestamp. Does NOT verify the signature or parse tagged fields beyond basic extraction.

Args: invoice: BOLT11 payment request string (starts with lnbc, lntb, or lnbcrt)

Inputs: invoice (required). Returns: result

decode_raw_transactionB

Decode a raw transaction hex without looking up inputs.

Args: hex_string: Raw transaction in hex format

Inputs: hex_string (required). Returns: result

decode_xpubC

Derive addresses and metadata from an extended public key.

Inputs: xpub (required), account, derive_count. Returns: result

describe_rpc_commandA

Get structured help for a Bitcoin RPC command: description, arguments, examples.

Args: command: RPC command name (e.g. "getblock", "sendrawtransaction")

Inputs: command (required). Returns: result

estimate_smart_feeC

Get fee estimate for a specific confirmation target.

Args: conf_target: Number of blocks for confirmation (1-1008)

Inputs: conf_target (required). Returns: result

estimate_transaction_costA

Estimate Bitcoin transaction cost in sats AND USD at different urgency levels. Supports address types: p2pkh (legacy), p2sh-p2wpkh (nested segwit), p2wpkh (native segwit), p2tr (taproot). Shows how much you save by waiting.

Inputs: input_count, address_type, output_count. Returns: result

explain_inscription_listing_securityA

Explain in plain language whether an ordinals inscription listing is snipe-resistant.

Analyzes the PSBT and returns a human-readable explanation of:

  • Whether the listing can be front-run in the mempool

  • What sighash type each input uses and why it matters

  • Specific remediation steps if the listing is vulnerable

Use this when you need a clear explanation for a developer or marketplace operator rather than raw analysis data.

Args: psbt_hex: Hex-encoded PSBT string (BIP 174 v0)

Inputs: psbt_hex (required). Returns: result

explain_scriptB

Decode a Bitcoin Script hex and break down the opcodes.

Args: hex_script: Script in hex format

Inputs: hex_script (required). Returns: result

generate_keypairA

Generate a new Bitcoin address via the connected node's wallet. Requires a local node with a wallet loaded — not available when using the hosted Satoshi API.

SECURITY: Private keys are redacted by default because AI provider tool responses may be logged. Set include_private_key=True only if you understand the risk — the key will appear in your conversation history and should be considered potentially compromised for high-value use.

Args: address_type: Address type — "legacy" (P2PKH), "p2sh-segwit" (P2SH-P2WPKH), "bech32" (P2WPKH, default), or "bech32m" (P2TR taproot) include_private_key: If True, include the WIF private key in the response. Defaults to False for security.

Inputs: address_type, include_private_key. Returns: result

get_address_balanceA

Get the total balance, transaction count, and first/last seen times for a Bitcoin address.

Uses the Satoshi API blockchain indexer when available, falls back to mempool.space. Returns total received, total sent, current balance, tx count, and timestamps.

Args: address: Bitcoin address (any format: legacy, P2SH, bech32, bech32m)

Inputs: address (required). Returns: result

get_address_historyA

Get paginated transaction history for a Bitcoin address.

Uses the Satoshi API blockchain indexer when available, falls back to mempool.space. Shows each transaction with block height, timestamp, and net value change for the address. Results are ordered newest-first.

Args: address: Bitcoin address (any format) offset: Skip this many transactions (for pagination, default 0) limit: Max transactions to return (default 25, max 100)

Inputs: address (required), limit, offset. Returns: result

get_address_transactionsB

Get paginated transaction history for a Bitcoin address with per-tx value details.

Inputs: address (required), limit, offset. Returns: result

get_address_utxosA

Scan the UTXO set for all unspent outputs belonging to an address. Note: scans full UTXO set, may take minutes.

Args: address: Bitcoin address to scan

Inputs: address (required). Returns: result

get_blockchain_infoB

Get blockchain info: chain, difficulty, softfork statuses, chain work, pruning.

Inputs: no named parameters. Returns: result

get_block_countA

Get current block height (lightweight, fast).

Inputs: no named parameters. Returns: result

get_block_statsB

Get raw block statistics: median fee, total output, subsidy, weight, tx count.

Args: height: Block height

Inputs: height (required). Returns: result

get_btc_priceA

Get current BTC/USD price from CoinGecko (free, no API key). Returns price, 24h change, and market cap. Use this to convert sat/vB fees into dollar amounts.

Inputs: no named parameters. Returns: result

get_chain_tipsB

Get chain tips: active chain, forks, and stale branches. Useful for detecting chain splits.

Inputs: no named parameters. Returns: result

get_chain_tx_statsB

Get transaction rate statistics over N blocks.

Args: nblocks: Number of blocks to average over (default 2016 = ~2 weeks)

Inputs: nblocks. Returns: result

get_difficulty_adjustmentB

Calculate difficulty adjustment progress: blocks into epoch, blocks remaining, estimated time, and projected adjustment.

Inputs: no named parameters. Returns: result

get_fee_estimatesA

Get fee rate estimates for 1/3/6/25/144 block confirmation targets in sat/vB.

Inputs: no named parameters. Returns: result

get_fee_recommendationB

Get a plain-English fee recommendation based on current estimates, with raw rate data.

Inputs: no named parameters. Returns: result

get_halving_countdownA

Get a focused countdown to the next Bitcoin halving: blocks remaining, estimated date, and subsidy change.

Inputs: no named parameters. Returns: result

get_indexed_transactionA

Get enriched transaction details from the blockchain indexer.

Unlike analyze_transaction (which uses raw RPC), this returns resolved input addresses, spent/unspent status for each output, and block context. Falls back to mempool.space when the indexer is unavailable.

Args: txid: Transaction ID (64-character hex string)

Inputs: txid (required). Returns: result

get_indexer_statusA

Check the blockchain indexer sync progress.

Returns current indexed height, chain tip, sync percentage, blocks/sec, and ETA. Use this to check if the indexer is running and how far along the initial sync is.

Inputs: no named parameters. Returns: result

get_market_sentimentA

Get Bitcoin Fear & Greed Index: current value (0-100), classification (Extreme Fear/Fear/Neutral/Greed/Extreme Greed), and 7-day history. Use this to gauge market sentiment alongside price data.

Inputs: no named parameters. Returns: result

get_mempool_ancestorsA

Get all unconfirmed ancestor transactions of a mempool transaction. Useful for CPFP analysis.

Args: txid: Transaction hash (64 hex characters)

Inputs: txid (required). Returns: result

get_mempool_entryA

Get details of a specific unconfirmed transaction in the mempool.

Args: txid: Transaction hash (64 hex characters)

Inputs: txid (required). Returns: result

get_mempool_infoA

Get quick mempool stats: transaction count, size in bytes, min relay fee.

Inputs: no named parameters. Returns: result

get_mining_infoB

Get mining info: difficulty, network hashrate, current block size.

Inputs: no named parameters. Returns: result

get_mining_pool_rankingsA

Get top 10 Bitcoin mining pools by hashrate share over the last week. Returns pool name, percentage of total hashrate, and block count. Use this to understand mining centralization and pool dominance.

Inputs: no named parameters. Returns: result

get_network_infoA

Get network info: protocol version, relay fee, connections, warnings. In hosted API mode, reflects the API server's network view.

Inputs: no named parameters. Returns: result

get_node_statusA

Get Bitcoin network status: chain, height, sync progress, disk usage, connections, version. In hosted API mode, reflects the API server's node.

Inputs: no named parameters. Returns: result

get_peer_infoA

Get connected peer details: addresses, latency, services, version. In hosted API mode, shows the API server's peers.

Inputs: no named parameters. Returns: result

get_situation_summaryA

Get a quick Bitcoin briefing: price, fees, mempool, and chain tip in one call. Use this as your first call to understand current conditions — replaces calling 5+ tools separately.

Inputs: no named parameters. Returns: result

get_supply_infoA

Get Bitcoin supply data: circulating supply, max supply, inflation rate, subsidy per block, and next halving estimate.

Inputs: no named parameters. Returns: result

get_utxo_set_infoA

Get UTXO set statistics: total UTXOs, total supply, disk size. Note: this is a slow operation (1-2 minutes on local nodes, may vary on hosted API).

Inputs: no named parameters. Returns: result

list_rpc_commandsB

List all available RPC commands grouped by category.

Inputs: no named parameters. Returns: result

search_blockchainA

Smart search: auto-detects if query is a txid, block hash, block height, or address and returns the right data.

Args: query: A txid (64 hex), block hash (64 hex starting with 0000), block height (number), or Bitcoin address

Inputs: query (required). Returns: result

search_blocksB

Get block statistics for a range of heights. Max 10 blocks.

Args: start_height: Starting block height (inclusive) end_height: Ending block height (inclusive)

Inputs: end_height (required), start_height (required). Returns: result

send_raw_transactionA

Broadcast a signed raw transaction to the Bitcoin network.

WARNING: This sends a REAL transaction. Once broadcast, it cannot be reversed. Ensure the transaction is correctly signed and you understand the fee implications. In hosted API mode, the transaction is broadcast through the Satoshi API's node.

Args: hex_string: Signed raw transaction in hex format max_fee_rate: Maximum fee rate in BTC/kvB to prevent accidental overpayment (default 0.10)

Inputs: hex_string (required), max_fee_rate. Returns: result

validate_addressA

Validate a Bitcoin address and return its type (legacy/segwit/taproot), network, and script info. Use this to check if an address is valid before sending, or to identify what kind of address you're looking at.

Args: address: Bitcoin address to validate (any format: P2PKH, P2SH, P2WPKH, P2WSH, P2TR)

Inputs: address (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 50 tools

    Disambiguation2/5

    There are many overlapping tools: get_address_transactions vs get_address_history vs get_indexed_transaction; analyze_transaction vs get_indexed_transaction vs decode_raw_transaction; get_market_sentiment vs get_btc_price; multiple fee tools (get_fee_estimates, get_fee_recommendation, estimate_smart_fee, compare_fee_estimates, estimate_transaction_cost); multiple mempool tools (analyze_mempool, get_mempool_info) and repeated node-info tools. Descriptions help somewhat, but the boundaries between several tools are blurry enough that an agent will frequently misselect.

    Naming Consistency4/5

    Nearly all tools use a consistent verb_noun or snake_case pattern (get_, analyze_, decode_, send_, estimate_). A few like analyze_next_block, search_blockchain, and describe_rpc_command are slightly less conventional but still readable. No camelCase mixing or chaotic styles.

    Tool Count2/5

    50 tools is far too many for a single Bitcoin utility server; the surface sprawls across RPC access, fee estimation, mempool analysis, mining, address tools, PSBT security, and Lightning decoding. Several near-duplicate tools exist that could be consolidated, suggesting an overloaded rather than well-scoped set.

    Completeness4/5

    The domain coverage is broad and there are few obvious dead ends: block, transaction, mempool, fee, mining, address, supply, and PSBT tooling are all present. Some gaps remain (e.g., no explicit wallet/transaction-construction or tracked-address registration flow), but core workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides real Bitcoin full node data via 17 tools, with pay-per-call in USDC on Base mainnet. Free tools include blockchain info, fees, and mempool; paid tools enable transaction tracking, address analysis, and more.
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Enables AI applications to interact with the Bitcoin Network, manage wallets, check balances, convert prices, and send transactions.
      4
      51 npm
      6
      MIT