io.github.Bortlesboat/bitcoin-mcp

Official

by Bortlesboat · Python

Bitcoin MCP

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

49 Bitcoin tools for fees, mempool, blocks, mining, and price data.

Topics

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

README.md13 KBView on GitHub

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.

bash

pip install bitcoin-mcp

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

json

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

Claude Code

bash

claude mcp add bitcoin -- uvx bitcoin-mcp

Cursor

Add to .cursor/mcp.json:

json

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

VS Code

Add to .vscode/mcp.json:

json

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

Zed

Add to your Zed settings.json under context_servers:

json

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

bash

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:

The agent calls get_fee_recommendation.
The answer gives a clear send now or wait recommendation with fee rates in sat/vB.
If you will repeat this check, register a free Satoshi API key and add SATOSHI_API_KEY to your MCP config.
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):

Visit bitcoinsapi.com
Register for a free key (takes 10 seconds)
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:

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`	Override hosted API URL	`https://bitcoinsapi.com`
`SATOSHI_API_KEY`	API key for authenticated access	None

To connect to a local Bitcoin Core node:

json

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

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

Install

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)

claude_desktop_config.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>"
      }
    }
  }
}

Topics

bitcoin-mcp

Quick Start

Claude Desktop

Claude Code

Cursor

VS Code

Zed

Docker

Ask whether to send Bitcoin now

Agent Integration

Why bitcoin-mcp?

Top Use Cases

Full Tool Reference

Fee Intelligence

Blocks & Transactions

Mempool

Mining

Network & Status

Address & UTXO

Indexed Address (requires blockchain indexer)

Security

Utility

Get More Requests (Free)

Configuration

CLI Flags

Prompts & Resources

Links

Examples

Support This Project

Contributing

About

License

Install

Configuration