{
  "markdown": "# bitcoin-mcp\n<!-- mcp-name: io.github.Bortlesboat/bitcoin-mcp -->\n\nGive any AI agent Bitcoin superpowers — fee intelligence, mempool analysis, and 50 tools backed by your Bitcoin node or compatible API.\n\n[![PyPI](https://img.shields.io/pypi/v/bitcoin-mcp)](https://pypi.org/project/bitcoin-mcp/)\n[![Downloads](https://img.shields.io/pypi/dm/bitcoin-mcp)](https://pypi.org/project/bitcoin-mcp/)\n[![Tests](https://github.com/Bortlesboat/bitcoin-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/Bortlesboat/bitcoin-mcp/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![GitHub Sponsors](https://img.shields.io/badge/Support-GitHub%20Sponsors-ea4aaa)](https://github.com/sponsors/Bortlesboat)\n\n**50 standard tools** · **6 prompts** · **8 resources** · **Bitcoin Core or compatible API backend** · **MIT licensed**\n\n> If bitcoin-mcp is useful to you, consider giving it a [star](https://github.com/Bortlesboat/bitcoin-mcp/stargazers) — it helps others discover the project.\n\n```bash\npip install \"bitcoin-mcp>=0.5.2\"\n```\n\nbitcoin-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.\n\n> **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.\n\n## Install status\n\nVersion 0.5.2 includes the MCP SDK 1.x compatibility constraint and explicit backend selection. Upgrade older installations to receive these fixes.\n\n## Quick Start\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"bitcoin\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"bitcoin-mcp>=0.5.2\", \"bitcoin-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add bitcoin -- uvx --from \"bitcoin-mcp>=0.5.2\" bitcoin-mcp\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"bitcoin\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"bitcoin-mcp>=0.5.2\", \"bitcoin-mcp\"]\n    }\n  }\n}\n```\n\n### VS Code\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"bitcoin\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"bitcoin-mcp>=0.5.2\", \"bitcoin-mcp\"]\n    }\n  }\n}\n```\n\n### Zed\n\nAdd to your Zed `settings.json` under `context_servers`:\n\n```json\n{\n  \"context_servers\": {\n    \"bitcoin\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"bitcoin-mcp>=0.5.2\", \"bitcoin-mcp\"]\n    }\n  }\n}\n```\n\nSee the [Zed MCP docs](https://zed.dev/docs/ai/mcp) for the current settings location and custom server flow.\n\n### Docker\n\n```bash\ndocker build -t bitcoin-mcp .\ndocker run -i bitcoin-mcp\n```\n\nOr with docker compose:\n\n```bash\ndocker compose up\n```\n\nPass environment variables to connect to a local Bitcoin Core node or a compatible API:\n\n```bash\ndocker run -i -e BITCOIN_RPC_HOST=host.docker.internal -e BITCOIN_RPC_PORT=8332 bitcoin-mcp\n# or\ndocker run -i -e SATOSHI_API_URL=https://your-api.example bitcoin-mcp\n```\n\n### Ask whether to send Bitcoin now\n\nUse this as the first useful activation path after install:\n\n> \"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.\"\n\nExpected path:\n\n1. The agent calls `get_fee_recommendation`.\n2. The answer gives a clear send now or wait recommendation with fee rates in sat/vB.\n3. If the backend is unavailable, configure a local node or set `SATOSHI_API_URL` before retrying.\n\nAfter 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.\n\n## Agent Integration\n\nFor repos that need Bitcoin tools, add `bitcoin-mcp` to the agent's MCP config and configure one of its supported backends:\n\n- Local Bitcoin Core/Knots RPC settings: `BITCOIN_RPC_HOST`, `BITCOIN_RPC_PORT`, and optional credentials or datadir\n- Compatible remote API: `SATOSHI_API_URL` and, when required, `SATOSHI_API_KEY`\n- Satoshi API source and integration reference: https://github.com/Bortlesboat/bitcoin-api/blob/master/docs/AGENT_INTEGRATION.md\n\nGenerated HTTP examples should use canonical Satoshi API `/api/v1` paths.\n\n## Why bitcoin-mcp?\n\n- **Fee intelligence that saves real money** — know the cheapest time to send, compare fee tiers, estimate exact costs before broadcasting\n- **Backend choice** — use your own Bitcoin Core/Knots node or an explicitly configured compatible API\n- **Open source MCP tooling** — tool definitions, tests, and client configuration examples are available in this repository\n\n## Top Use Cases\n\nAsk your AI agent:\n\n| Prompt | What it does |\n|--------|-------------|\n| \"What's the cheapest time to send Bitcoin today?\" | Fee recommendation with savings breakdown |\n| \"Analyze the current mempool congestion\" | Real-time mempool depth, fee tiers, pending tx count |\n| \"How much would I save waiting 6 blocks vs next block?\" | Side-by-side fee comparison across confirmation targets |\n| \"Search for this transaction: abc123...\" | Full transaction decode with inscription detection |\n| \"Give me a situation summary of Bitcoin right now\" | Price, fees, mempool, mining, difficulty — one call |\n\n## Full Tool Reference\n\n<details>\n<summary>All 50 standard tools by category</summary>\n\n### Fee Intelligence\n| Tool | Description |\n|------|-------------|\n| `get_fee_recommendation` | Optimal fee rate with urgency tiers and savings tips |\n| `get_fee_estimates` | Fee estimates across all confirmation targets |\n| `estimate_smart_fee` | Fee estimate for a specific confirmation target |\n| `compare_fee_estimates` | Side-by-side comparison of fee sources |\n| `estimate_transaction_cost` | Exact cost estimate for a transaction before sending |\n\n### Blocks & Transactions\n| Tool | Description |\n|------|-------------|\n| `analyze_block` | Deep analysis of any block by height or hash |\n| `get_block_stats` | Statistical breakdown of a block |\n| `get_block_count` | Current chain height |\n| `compare_blocks` | Compare two blocks side by side |\n| `search_blocks` | Search a range of blocks |\n| `analyze_transaction` | Full transaction analysis with inscription detection |\n| `decode_raw_transaction` | Decode a raw transaction hex |\n| `send_raw_transaction` | Broadcast a signed transaction |\n| `check_utxo` | Check if a UTXO is spent or unspent |\n\n### Mempool\n| Tool | Description |\n|------|-------------|\n| `analyze_mempool` | Full mempool analysis — depth, fees, congestion |\n| `get_mempool_info` | Mempool size, bytes, fee floor |\n| `get_mempool_entry` | Details for a specific unconfirmed transaction |\n| `get_mempool_ancestors` | Ancestor chain for a mempool transaction |\n\n### Mining\n| Tool | Description |\n|------|-------------|\n| `get_mining_info` | Current mining difficulty, hashrate, block reward |\n| `analyze_next_block` | Preview of the next block template |\n| `get_mining_pool_rankings` | Top mining pools by recent blocks |\n| `get_difficulty_adjustment` | Time and percentage of next difficulty change |\n| `get_halving_countdown` | Blocks and estimated time until next halving |\n\n### Network & Status\n| Tool | Description |\n|------|-------------|\n| `get_blockchain_info` | Chain state, verification progress, softfork status |\n| `get_network_info` | Node version, connections, relay info |\n| `get_node_status` | Connection status and node health |\n| `get_peer_info` | Connected peer details |\n| `get_chain_tips` | Active and stale chain tips |\n| `get_chain_tx_stats` | Transaction throughput over N blocks |\n| `get_utxo_set_info` | UTXO set size and total supply |\n| `get_supply_info` | Circulating supply, inflation rate, percent mined |\n| `get_situation_summary` | Aggregated overview — price, fees, mempool, mining |\n| `get_btc_price` | Current BTC/USD price |\n| `get_market_sentiment` | Fear/greed index and market indicators |\n\n### Address & UTXO\n| Tool | Description |\n|------|-------------|\n| `get_address_utxos` | UTXOs for an address |\n| `validate_address` | Validate and classify a Bitcoin address |\n\n### Indexed Address (requires blockchain indexer)\n| Tool | Description |\n|------|-------------|\n| `get_address_balance` | Total received/sent/balance, tx count, first/last seen |\n| `get_address_history` | Paginated transaction history with net value change |\n| `get_address_transactions` | Transaction history with per-transaction value details |\n| `get_indexed_transaction` | Enriched tx with resolved input addresses + spent status |\n| `get_indexer_status` | Sync progress, ETA, blocks/sec |\n\n### Security\n| Tool | Description |\n|------|-------------|\n| `analyze_psbt_security` | Security analysis of a Partially Signed Bitcoin Transaction |\n| `explain_inscription_listing_security` | Security guide for ordinal inscription listings |\n\n### Utility\n| Tool | Description |\n|------|-------------|\n| `search_blockchain` | Universal search — address, txid, block hash, or height |\n| `generate_keypair` | Generate a new Bitcoin keypair |\n| `explain_script` | Decode and explain a Bitcoin script |\n| `decode_bolt11_invoice` | Decode a Lightning Network BOLT11 invoice |\n| `describe_rpc_command` | Help text for any Bitcoin Core RPC command |\n| `list_rpc_commands` | List all available RPC commands |\n| `decode_xpub` | Decode and inspect an extended public key |\n\n### Optional Remote API Tool\n\n`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.\n\n</details>\n\n## Configuration\n\nConfigure 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.\n\n### CLI Flags\n\n`bitcoin-mcp` supports the following runtime flags:\n\n| Flag | Values | Default | Description |\n|------|--------|---------|-------------|\n| `--transport` | `stdio`, `sse`, `streamable-http` | `stdio` | MCP transport to run |\n| `--host` | hostname / IP | `127.0.0.1` for HTTP transports | Bind host for `sse` and `streamable-http` |\n| `--port` | integer | `8000` for HTTP transports | Bind port for `sse` and `streamable-http` |\n| `--log-level` | `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` | Server log verbosity |\n\nExample:\n\n```bash\nbitcoin-mcp --transport sse --host 127.0.0.1 --port 8000 --log-level DEBUG\n```\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `BITCOIN_RPC_HOST` | Bitcoin Core RPC host | `127.0.0.1` |\n| `BITCOIN_RPC_PORT` | Bitcoin Core RPC port | Auto by network |\n| `BITCOIN_NETWORK` | `mainnet`, `testnet`, `signet`, or `regtest` | `mainnet` |\n| `SATOSHI_API_URL` | Compatible Satoshi API base URL | None |\n| `SATOSHI_API_KEY` | API key for authenticated access | None |\n\nTo connect to a local Bitcoin Core node:\n\n```json\n{\n  \"mcpServers\": {\n    \"bitcoin\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"bitcoin-mcp>=0.5.2\", \"bitcoin-mcp\"],\n      \"env\": {\n        \"BITCOIN_RPC_HOST\": \"127.0.0.1\",\n        \"BITCOIN_RPC_PORT\": \"8332\"\n      }\n    }\n  }\n}\n```\n\n## Prompts & Resources\n\n**6 built-in prompts** for common workflows:\n`analyze_fee_environment`, `investigate_transaction`, `monitor_mempool_fees`, `taproot_adoption_report`, `network_health_report`, `track_transaction`\n\n**8 resources** for context injection:\n`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`\n\n## Links\n\n- [Satoshi API source](https://github.com/Bortlesboat/bitcoin-api) — optional compatible backend implementation (public hosted service currently paused)\n- [MCP Registry](https://registry.modelcontextprotocol.io) — `io.github.Bortlesboat/bitcoin-mcp`\n- [PyPI](https://pypi.org/project/bitcoin-mcp/)\n- [GitHub](https://github.com/Bortlesboat/bitcoin-mcp)\n- [Full tool documentation](https://github.com/Bortlesboat/bitcoin-mcp#full-tool-reference)\n\n## Examples\n\nSee the [examples/](examples/) folder for documented usage patterns:\n- [Fee Analysis](examples/fee_analysis.py) — find optimal send timing\n- [Mempool Monitor](examples/mempool_monitor.py) — track congestion\n- [Transaction Investigation](examples/transaction_investigation.py) — decode and analyze transactions\n- [Block Analysis](examples/block_analysis.py) — inspect and compare blocks\n\n## Support This Project\n\nbitcoin-mcp is free, open-source Bitcoin infrastructure. Support development through [GitHub Sponsors](https://github.com/sponsors/Bortlesboat), reproducible issue reports, documentation improvements, and tested patches.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, including how to add new tools and the PR checklist.\n\nPlease report security vulnerabilities privately — see [SECURITY.md](SECURITY.md).\n\n## About\n\nbitcoin-mcp is created and maintained by [Andrew Barnes](https://github.com/Bortlesboat), bridging AI agents and Bitcoin infrastructure through the Model Context Protocol.\n\nRelated projects:\n- [Satoshi API](https://github.com/Bortlesboat/bitcoin-api) — Bitcoin fee intelligence API, 108 endpoints, usable as a self-hosted compatible backend\n- [ChainPulse](https://github.com/Bortlesboat/chainpulse) — AI-powered Bitcoin network intelligence CLI\n- [BAIP-1](https://github.com/Bortlesboat/baip-python) — Bitcoin Agent Identity Protocol\n- [bitcoin-fee-observatory](https://github.com/Bortlesboat/bitcoin-fee-observatory) — Fee market analytics dashboard\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 13797,
  "sha": "824b1f5d5b23e76091504225a719a6ca3d5a0368d47216f1f2717361649a3163",
  "repo_slug": "bortlesboat/bitcoin-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bortlesboat_bitcoin_mcp_1d85ca33/readme"
}