Purpose
bitcoin-mcp is aimed at AI agents that need Bitcoin capabilities, connecting Bitcoin infrastructure into agent workflows through the Model Context Protocol (MCP). It provides 50 standard Bitcoin tools, 6 prompts, and 8 resources, enabling agents to perform fee intelligence, mempool analysis, block and transaction inspection, and other operations.
Main Capabilities
- Fee intelligence: determine the cheapest time to send, compare fee rate tiers, and estimate the exact cost before broadcasting. For example, an agent can call get_fee_recommendation to get a "send now or wait" recommendation, along with a fee rate in sat/vB.
- Blocks and transactions: decode and analyze transactions, and inspect and compare blocks.
- Network and status: provide information related to network and node status.
- Indexed addresses: require blockchain indexer support.
- Optional remote API: when SATOSHI_API_URL is set and the l402 extra dependency is installed, query_remote_api is registered for querying the canonical /api/v1 routes on an explicitly configured endpoint.
Prompts and resources: built-in 6 common workflow prompts (analyze_fee_environment, investigate_transaction, monitor_mempool_fees, taproot_adoption_report, network_health_report, track_transaction) and 8 resources for context injection (such as bitcoin://connection/status, bitcoin://node/status, bitcoin://fees/current, bitcoin://fees/history, bitcoin://mempool/snapshot, and protocol-related resources).
Usage
The project requires a Bitcoin data backend and automatically detects it from the cookie or RPC settings of a local Bitcoin Core/Knots node; when there is no local node, SATOSHI_API_URL must be set to point to a compatible deployment. It supports being added to claude_desktop_config.json, .cursor/mcp.json, .vscode/mcp.json, and Zed's settings.json (under context_servers), and can also be run with docker compose.
When connecting to a local Bitcoin Core node, configuration can be passed through environment variables: BITCOIN_RPC_HOST, BITCOIN_RPC_PORT, and optional credentials or datadir; when connecting to a compatible remote API, use SATOSHI_API_URL, and if necessary SATOSHI_API_KEY. The project also provides runtime flags.
A typical activation path is to ask the agent: "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." The agent will call get_fee_recommendation and return a clear send-or-wait recommendation and fee rate. If the backend is unavailable, configure a local node or set SATOSHI_API_URL first and then retry.
Applicable Scenarios
Suitable for development repositories and agent integration scenarios that need Bitcoin tools, such as building AI agents that interact with Bitcoin, performing fee analysis and mempool monitoring, transaction investigation, block analysis, and so on. The examples/ folder provides usage pattern examples such as fee analysis, mempool monitoring, transaction investigation, and block analysis.
Limitations and Notes
- The project requires a usable data backend. If neither a local node nor a compatible remote API is available, bitcoin-mcp will exit the connection check with a setup error rather than silently choosing an unavailable public service.
- The public Satoshi API formerly hosted at bitcoinsapi.com has been suspended and should not be regarded as an available default service.
- Version 0.5.2 includes MCP SDK 1.x compatibility constraints and explicit backend selection; older installations are advised to upgrade.
- bitcoin-mcp is free, open-source Bitcoin infrastructure, and development is supported through methods such as GitHub Sponsors.
- Related projects include Satoshi API (a self-hostable compatible backend), ChainPulse, BAIP-1, and bitcoin-fee-observatory。
