Bitcoin MCP

Official49 tools

by Bortlesboat · Python

49 Bitcoin tools for AI agents: fees, mempool, blocks, mining, price. Zero config.

io.github.Bortlesboat/bitcoin-mcp — MCP Server for Bitcoin Data

This MCP server provides 49 Bitcoin tools for AI agents, covering fee intelligence, mempool analysis, blocks, mining, and price. It is described as “zero config” and relies on a Bitcoin node or a compatible API to back the tool set.

🛠️ Key Features

49 tools for Bitcoin-related tasks
Fee intelligence and fee estimation
Mempool analysis
Blocks and mining data
Price access
Backed by a Bitcoin node or compatible API
Zero configuration

🚀 Use Cases

Building AI agents that need current Bitcoin information
Agent workflows that evaluate transaction fees
Monitoring mempool conditions and block activity
Mining and price-aware agent logic
Integrations with MCP-based clients

⚡ Developer Benefits

MCP server compatible with Model Context Protocol
Topics indicate support for AI agents, LLM use, and Python
Designed for self-hosted deployment
Works with Bitcoin Core and Bitcoin node-compatible APIs

⚠️ Limitations

No additional capabilities beyond the listed areas (fees, mempool, blocks, mining, price) are described
“Zero config” is stated, but setup/authentication requirements are not detailed

Topics

ai-agentsbitcoinmcpmodel-context-protocolpythonbitcoin-apibitcoin-corebitcoin-nodeblockchainclaudecryptocurrencyllmmcp-serverself-hostedanthropicclaude-desktopcursorfee-estimationbitcoin-mcpmempool

Declared in the repository manifest (tools.json). Not verified against a live endpoint.

get_fee_recommendation

Optimal fee rate with urgency tiers and savings tips

Parameters

No parameters.

get_fee_estimates

Fee estimates for 1/3/6/25/144 block confirmation targets in sat/vB

Parameters

No parameters.

estimate_smart_fee

Fee estimate for a specific confirmation target (1-1008 blocks)

Parameters

No parameters.

compare_fee_estimates

Side-by-side fee comparison with urgency labels and cost for a typical 140 vB transaction

Parameters

No parameters.

estimate_transaction_cost

Estimate transaction cost in sats and USD at different urgency levels by address type

Parameters

No parameters.

analyze_block

Deep block analysis: mining pool, SegWit/Taproot adoption, fee distribution, revenue

Parameters

No parameters.

get_block_stats

Raw block statistics: median fee, total output, subsidy, weight, tx count

Parameters

No parameters.

get_block_count

Current chain height (lightweight, fast)

Parameters

No parameters.

compare_blocks

Compare block statistics between two heights side by side

Parameters

No parameters.

search_blocks

Get block statistics for a range of heights (max 10)

Parameters

No parameters.

analyze_transaction

Full transaction analysis with inscription detection

Parameters

No parameters.

decode_raw_transaction

Decode a raw transaction hex without looking up inputs

Parameters

No parameters.

check_utxo

Check if a specific transaction output is spent or unspent

Parameters

No parameters.

send_raw_transaction

Broadcast a signed raw transaction to the Bitcoin network

Parameters

No parameters.

analyze_mempool

Full mempool analysis: tx count, fee buckets, congestion level, next-block minimum fee

Parameters

No parameters.

get_mempool_info

Quick mempool stats: transaction count, size in bytes, min relay fee

Parameters

No parameters.

get_mempool_entry

Details for a specific unconfirmed transaction in the mempool

Parameters

No parameters.

get_mempool_ancestors

Ancestor chain for a mempool transaction (useful for CPFP analysis)

Parameters

No parameters.

get_mining_info

Current mining difficulty, hashrate, block size

Parameters

No parameters.

analyze_next_block

Predict next block: transactions, weight utilization, revenue, fee percentiles

Parameters

No parameters.

get_mining_pool_rankings

Top 10 mining pools by hashrate share over the last week

Parameters

No parameters.

get_difficulty_adjustment

Difficulty adjustment progress: blocks remaining, estimated time, projected change

Parameters

No parameters.

get_halving_countdown

Blocks and estimated time until next halving with subsidy change

Parameters

No parameters.

get_blockchain_info

Chain state, difficulty, softfork statuses, chain work, pruning

Parameters

No parameters.

get_network_info

Node version, connections, relay info

Parameters

No parameters.

get_node_status

Connection status and node health

Parameters

No parameters.

get_peer_info

Connected peer details: addresses, latency, services, version

Parameters

No parameters.

get_chain_tips

Active and stale chain tips for detecting chain splits

Parameters

No parameters.

get_chain_tx_stats

Transaction throughput over N blocks

Parameters

No parameters.

get_utxo_set_info

UTXO set size and total supply

Parameters

No parameters.

get_supply_info

Circulating supply, inflation rate, percent mined, next halving estimate

Parameters

No parameters.

get_btc_price

Current BTC/USD price from CoinGecko with 24h change and market cap

Parameters

No parameters.

get_market_sentiment

Fear & Greed Index: current value, classification, and 7-day history

Parameters

No parameters.

get_address_utxos

Scan UTXO set for all unspent outputs belonging to an address

Parameters

No parameters.

validate_address

Validate and classify a Bitcoin address (legacy/segwit/taproot)

Parameters

No parameters.

get_address_balance

Total received/sent/balance, tx count, first/last seen for an address

Parameters

No parameters.

get_address_history

Paginated transaction history with net value change for an address

Parameters

No parameters.

get_indexed_transaction

Enriched transaction with resolved input addresses and spent status

Parameters

No parameters.

get_indexer_status

Blockchain indexer sync progress, ETA, blocks/sec

Parameters

No parameters.

analyze_psbt_security

Analyze a PSBT for ordinals inscription listing sniping vulnerability

Parameters

No parameters.

explain_inscription_listing_security

Plain-language explanation of whether an ordinals listing is snipe-resistant

Parameters

No parameters.

get_situation_summary

Aggregated Bitcoin briefing: price, fees, mempool, chain tip in one call

Parameters

No parameters.

search_blockchain

Smart search: auto-detects txid, block hash, height, or address

Parameters

No parameters.

generate_keypair

Generate a new Bitcoin address via the connected node's wallet

Parameters

No parameters.

explain_script

Decode and explain a Bitcoin script's opcodes

Parameters

No parameters.

decode_bolt11_invoice

Decode a Lightning Network BOLT11 invoice

Parameters

No parameters.

describe_rpc_command

Help text for any Bitcoin Core RPC command

Parameters

No parameters.

list_rpc_commands

List all available RPC commands by category

Parameters

No parameters.

query_remote_api

Query the Satoshi API directly with optional L402 micropayments

Parameters

No parameters.

README.md14 KBView on GitHub

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.

bash

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:

json

{
  "mcpServers": {
    "bitcoin": {
      "command": "uvx",
      "args": ["--from", "bitcoin-mcp>=0.5.2", "bitcoin-mcp"]
    }
  }
}

Claude Code

bash

claude mcp add bitcoin -- uvx --from "bitcoin-mcp>=0.5.2" bitcoin-mcp

Cursor

Add to .cursor/mcp.json:

json

{
  "mcpServers": {
    "bitcoin": {
      "command": "uvx",
      "args": ["--from", "bitcoin-mcp>=0.5.2", "bitcoin-mcp"]
    }
  }
}

VS Code

Add to .vscode/mcp.json:

json

{
  "servers": {
    "bitcoin": {
      "command": "uvx",
      "args": ["--from", "bitcoin-mcp>=0.5.2", "bitcoin-mcp"]
    }
  }
}

Zed

Add to your Zed settings.json under context_servers:

json

{
  "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

bash

docker build -t bitcoin-mcp .
docker run -i bitcoin-mcp

Or with docker compose:

bash

docker compose up

Pass environment variables to connect to a local Bitcoin Core node or a compatible API:

bash

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:

The agent calls get_fee_recommendation.
The answer gives a clear send now or wait recommendation with fee rates in sat/vB.
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:

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

All 50 standard tools by category

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:

bash

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:

json

{
  "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:

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

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

Install

Tools (49)

get_fee_recommendationget_fee_estimatesestimate_smart_feecompare_fee_estimatesestimate_transaction_costanalyze_blockget_block_statsget_block_count

Configuration

Environment variables

BITCOIN_RPC_HOST

Bitcoin Core RPC host (default: 127.0.0.1)

BITCOIN_RPC_PORT

Bitcoin Core RPC port (default: auto-selected by network)

BITCOIN_NETWORK

Bitcoin network: mainnet, testnet, signet, or regtest (default: mainnet). Sets default RPC port if BITCOIN_RPC_PORT is not set.

SATOSHI_API_URL

Override the default hosted API URL (default: https://bitcoinsapi.com). The hosted API is used automatically when no local node is detected.

SATOSHI_API_KEYsecret

API key for authenticated access to the hosted Satoshi API (get one free at POST /api/v1/register)

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "bitcoin-mcp": {
      "command": "uvx",
      "args": [
        "bitcoin-mcp"
      ],
      "env": {
        "BITCOIN_RPC_HOST": "<YOUR_BITCOIN_RPC_HOST>",
        "BITCOIN_RPC_PORT": "<YOUR_BITCOIN_RPC_PORT>",
        "BITCOIN_NETWORK": "<YOUR_BITCOIN_NETWORK>",
        "SATOSHI_API_URL": "<YOUR_SATOSHI_API_URL>",
        "SATOSHI_API_KEY": "<YOUR_SATOSHI_API_KEY>"
      }
    }
  }
}