# bitcoin-mcp

> Bitcoin MCP server with 50 standard tools for agents to query and analyze the network through Bitcoin Core/Knots or a compatible API.

## Quick Start

Install: pip install bitcoin-mcp
Run: bitcoin-mcp (or uvx bitcoin-mcp)

Requires a local Bitcoin Core/Knots node or `SATOSHI_API_URL` pointing to a compatible API. The former public service at bitcoinsapi.com is paused and is not a working default.

## Tools

### Fee Intelligence (5 tools)
- get_fee_recommendation: Optimal fee rate with urgency tiers and savings tips
- get_fee_estimates: Fee estimates for 1/3/6/25/144 block confirmation targets in sat/vB
- estimate_smart_fee: Fee estimate for a specific confirmation target (1-1008 blocks)
- compare_fee_estimates: Side-by-side fee comparison with urgency labels and cost for a typical 140 vB transaction
- estimate_transaction_cost: Estimate transaction cost in sats and USD at different urgency levels by address type

### Blocks & Transactions (9 tools)
- analyze_block: Deep block analysis — mining pool, SegWit/Taproot adoption, fee distribution, revenue
- get_block_stats: Raw block statistics — median fee, total output, subsidy, weight, tx count
- get_block_count: Current chain height (lightweight, fast)
- compare_blocks: Compare block statistics between two heights side by side
- search_blocks: Get block statistics for a range of heights (max 10)
- analyze_transaction: Full transaction analysis with inscription detection
- decode_raw_transaction: Decode a raw transaction hex without looking up inputs
- send_raw_transaction: Broadcast a signed raw transaction to the Bitcoin network
- check_utxo: Check if a specific transaction output is spent or unspent

### Mempool (4 tools)
- analyze_mempool: Full mempool analysis — tx count, fee buckets, congestion level, next-block minimum fee
- get_mempool_info: Quick mempool stats — transaction count, size in bytes, min relay fee
- get_mempool_entry: Details for a specific unconfirmed transaction
- get_mempool_ancestors: Ancestor chain for a mempool transaction (CPFP analysis)

### Mining (5 tools)
- get_mining_info: Current mining difficulty, hashrate, block size
- analyze_next_block: Predict next block — transactions, weight, revenue, fee percentiles
- get_mining_pool_rankings: Top 10 mining pools by hashrate share over the last week
- get_difficulty_adjustment: Difficulty adjustment progress — blocks remaining, estimated time, projected change
- get_halving_countdown: Blocks and estimated time until next halving

### Network & Status (7 tools)
- get_blockchain_info: Chain state, difficulty, softfork statuses, chain work, pruning
- 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 (detecting chain splits)
- get_chain_tx_stats: Transaction throughput over N blocks
- get_utxo_set_info: UTXO set size and total supply

### Price & Market (4 tools)
- get_btc_price: Current BTC/USD price from CoinGecko
- get_supply_info: Circulating supply, inflation rate, percent mined, next halving estimate
- get_market_sentiment: Fear & Greed Index with 7-day history
- get_situation_summary: Aggregated Bitcoin briefing — price, fees, mempool, chain tip in one call

### Address & UTXO (2 tools)
- get_address_utxos: Scan UTXO set for all unspent outputs belonging to an address
- validate_address: Validate and classify a Bitcoin address (legacy/segwit/taproot)

### Indexed Address (5 tools, requires blockchain indexer)
- 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 and spent status
- get_indexer_status: Sync progress, ETA, blocks/sec

### Security (2 tools)
- analyze_psbt_security: Analyze a PSBT for ordinals inscription listing sniping vulnerability
- explain_inscription_listing_security: Plain-language explanation of whether a listing is snipe-resistant

### Utility (7 tools)
- search_blockchain: Smart search — auto-detects txid, block hash, height, or address
- generate_keypair: Generate a new Bitcoin address via the connected node's wallet
- explain_script: Decode and explain a Bitcoin script's opcodes
- 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 by category
- decode_xpub: Decode and inspect an extended public key

### Optional Remote API Tool
- query_remote_api: Registered only when SATOSHI_API_URL is set and the l402 extra is installed

## Configuration

Configure either a local Bitcoin Core/Knots node or a compatible remote API. No public remote endpoint is selected implicitly.

| 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 when required by the configured endpoint | None |

## Links

- GitHub: https://github.com/Bortlesboat/bitcoin-mcp
- PyPI: https://pypi.org/project/bitcoin-mcp/
- Satoshi API source: https://github.com/Bortlesboat/bitcoin-api
- Anthropic MCP Registry: https://registry.modelcontextprotocol.io
