Bitcoin MCP

bitcoin-mcp

为任意 AI Agent 赋予 Bitcoin 超能力——费用情报、内存池分析，以及由你的 Bitcoin 节点或兼容 API 支持的 50 个工具。

50 个标准工具 · 6 个提示词 · 8 个资源 · Bitcoin Core 或兼容 API 后端 · MIT 许可

如果 bitcoin-mcp 对你有用，可以考虑给它点个星——这能帮助更多人发现这个项目。

pip install "bitcoin-mcp>=0.5.2"

bitcoin-mcp 需要 Bitcoin 数据后端。它会根据 cookie 或 RPC 设置自动检测本地 Bitcoin Core/Knots 节点。如果没有本地节点，请设置 SATOSHI_API_URL，指向兼容的部署。

**服务状态：**此前托管在 bitcoinsapi.com 上的公共 Satoshi API 目前已暂停，不应将其视为可用的默认服务。请使用本地节点，或明确配置兼容的 API。

安装状态

0.5.2 版包含 MCP SDK 1.x 兼容性约束和显式后端选择功能。请将旧版本升级，以获取这些修复。

快速入门

Claude Desktop

在 claude_desktop_config.json 中添加：

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

Claude Code

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

Cursor

在 .cursor/mcp.json 中添加：

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

VS Code

在 .vscode/mcp.json 中添加：

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

Zed

在 Zed 的 settings.json 中，在 context_servers 下添加：

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

请参阅 Zed MCP 文档，了解当前设置位置和自定义服务流程。

Docker

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

或者使用 docker compose：

docker compose up

传入环境变量，以连接本地 Bitcoin Core 节点或兼容的 API：

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

询问现在是否应该发送 Bitcoin

安装后，可将此作为第一个实用的激活路径：

“我今天需要发送一笔 Bitcoin 交易。使用 bitcoin-mcp 判断现在发送还是等待，并展示你使用的费率。”

预期流程：

1. Agent 调用 get_fee_recommendation。
2. 答案会给出明确的立即发送或等待建议，并提供以 sat/vB 为单位的费率。
3. 如果后端不可用，请配置本地节点或设置 SATOSHI_API_URL，然后重试。

成功后，请为这个仓库点星，并分享一个简短的演示，展示提示词、工具调用和结果，让其他 Bitcoin Agent 构建者了解此流程。

Agent 集成

对于需要 Bitcoin 工具的仓库，请将 bitcoin-mcp 添加到 Agent 的 MCP 配置中，并配置其支持的后端之一：

• 本地 Bitcoin Core/Knots RPC 设置：BITCOIN_RPC_HOST、BITCOIN_RPC_PORT，以及可选的凭据或 datadir
• 兼容的远程 API：SATOSHI_API_URL，以及在需要时设置 SATOSHI_API_KEY
• Satoshi API 来源和集成参考：https://github.com/Bortlesboat/bitcoin-api/blob/master/docs/AGENT_INTEGRATION.md

生成的 HTTP 示例应使用规范的 Satoshi API /api/v1 路径。

为什么选择 bitcoin-mcp？

• 节省真金白银的费用情报——了解最适合发送的时间、比较不同费率档，并在广播前准确估算费用
• 可选后端——使用你自己的 Bitcoin Core/Knots 节点，或明确配置的兼容 API
• 开源 MCP 工具——此仓库提供工具定义、测试和客户端配置示例

主要使用场景

向你的 AI Agent 提问：

提示词	功能
"今天什么时候发送 Bitcoin 最便宜？"	提供费用建议及节省金额明细
"分析当前的内存池拥堵情况"	实时内存池深度、费用档位和待处理交易数量
"等待 6 个区块而不是下一个区块，能省多少钱？"	并排比较不同确认目标的费用
"搜索这笔交易：abc123..."	完整解码交易并检测铭文
"总结一下 Bitcoin 当前的状况"	价格、费用、内存池、挖矿、难度——一次调用全部获取

完整工具参考

按类别列出的全部 50 个标准工具

费用情报

工具	描述
get_fee_recommendation	提供最佳费率、紧急程度档位和节省费用的建议
get_fee_estimates	所有确认目标的费用估算
estimate_smart_fee	针对特定确认目标估算费用
compare_fee_estimates	并排比较不同来源的费用估算
estimate_transaction_cost	发送前精确估算交易费用

区块与交易

工具	描述
analyze_block	按高度或哈希深度分析任意区块
get_block_stats	区块统计数据明细
get_block_count	当前链高度
compare_blocks	并排比较两个区块
search_blocks	搜索一定范围内的区块
analyze_transaction	完整分析交易并检测铭文
decode_raw_transaction	解码原始交易十六进制数据
send_raw_transaction	广播已签名的交易
check_utxo	检查 UTXO 是否已花费

内存池

工具	描述
analyze_mempool	全面分析内存池——深度、费用、拥堵情况
get_mempool_info	内存池大小、字节数和费用下限
get_mempool_entry	特定未确认交易的详细信息
get_mempool_ancestors	内存池交易的祖先链

挖矿

工具	描述
get_mining_info	当前挖矿难度、算力和区块奖励
analyze_next_block	预览下一个区块模板
get_mining_pool_rankings	按近期区块数排名的顶级矿池
get_difficulty_adjustment	下次难度调整的时间和幅度
get_halving_countdown	距离下次减半的区块数和预计时间

网络与状态

工具	描述
get_blockchain_info	链状态、验证进度和软分叉状态
get_network_info	节点版本、连接数和中继信息
get_node_status	连接状态和节点健康状况
get_peer_info	已连接节点的详细信息
get_chain_tips	活跃和过时的链尖端
get_chain_tx_stats	最近 N 个区块的交易吞吐量
get_utxo_set_info	UTXO 集大小和总供应量
get_supply_info	流通供应量、通胀率和已挖出比例
get_situation_summary	汇总概览——价格、费用、内存池和挖矿
get_btc_price	当前 BTC/USD 价格
get_market_sentiment	恐惧与贪婪指数及市场指标

地址与 UTXO

工具	描述
get_address_utxos	地址对应的 UTXO
validate_address	验证并分类 Bitcoin 地址

已索引地址（需要区块链索引器）

工具	描述
get_address_balance	接收总额、发送总额、余额、交易数、首次和最近出现时间
get_address_history	分页交易历史及净值变化
get_address_transactions	交易历史及每笔交易的金额详情
get_indexed_transaction	已增强的交易信息，包含解析后的输入地址和花费状态
get_indexer_status	同步进度、预计剩余时间和每秒区块数

### 安全性 | 工具 | 描述 | |------|-------------| | `analyze_psbt_security` | 对部分签名的 Bitcoin 交易进行安全分析 | | `explain_inscription_listing_security` | ordinal 铭文挂牌的安全指南 |

实用工具

工具	描述
search_blockchain	通用搜索——地址、txid、区块哈希或高度
generate_keypair	生成新的 Bitcoin 密钥对
explain_script	解码并解释 Bitcoin 脚本
decode_bolt11_invoice	解码 Lightning Network BOLT11 发票
describe_rpc_command	任意 Bitcoin Core RPC 命令的帮助文本
list_rpc_commands	列出所有可用的 RPC 命令
decode_xpub	解码并检查扩展公钥

可选远程 API 工具

仅当设置了 SATOSHI_API_URL 且安装了 l402 扩展时，才会注册 query_remote_api。它会查询该明确配置的端点上的规范 /api/v1 路由。

配置

配置本地 Bitcoin Core/Knots 节点或兼容的远程 API。如果两者均不可用，bitcoin-mcp 会在连接检查时退出并显示设置错误，而不会静默选择不可用的公共服务。

CLI 标志

bitcoin-mcp 支持以下运行时标志：

标志	值	默认值	描述
--transport	stdio、sse、streamable-http	stdio	要运行的 MCP 传输方式
--host	主机名 / IP	HTTP 传输方式为 127.0.0.1	sse 和 streamable-http 的绑定主机
--port	整数	HTTP 传输方式为 8000	sse 和 streamable-http 的绑定端口
--log-level	DEBUG、INFO、WARNING、ERROR	INFO	服务日志详细程度

示例：

bitcoin-mcp --transport sse --host 127.0.0.1 --port 8000 --log-level DEBUG

变量	描述	默认值
BITCOIN_RPC_HOST	Bitcoin Core RPC 主机	127.0.0.1
BITCOIN_RPC_PORT	Bitcoin Core RPC 端口	根据网络自动设置
BITCOIN_NETWORK	mainnet、testnet、signet 或 regtest	mainnet
SATOSHI_API_URL	兼容的 Satoshi API 基础 URL	无
SATOSHI_API_KEY	用于身份验证访问的 API 密钥	无

连接到本地 Bitcoin Core 节点：

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

提示词与资源

6 个内置提示词，适用于常见工作流： analyze_fee_environment、investigate_transaction、monitor_mempool_fees、taproot_adoption_report、network_health_report、track_transaction

8 个资源，用于上下文注入： 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

链接

• Satoshi API 源代码 — 可选的兼容后端实现（当前暂停提供公开托管服务）
• MCP Registry — io.github.Bortlesboat/bitcoin-mcp
• PyPI
• GitHub
• 完整工具文档

示例

请参阅 examples/ 文件夹，了解有文档说明的用法模式：

• 费用分析 — 找出最佳发送时机
• 内存池监控 — 跟踪拥堵情况
• 交易调查 — 解码并分析交易
• 区块分析 — 检查并比较区块

支持本项目

bitcoin-mcp 是免费的开源 Bitcoin 基础设施。您可以通过 GitHub Sponsors、提供可复现的问题报告、改进文档以及提交经过测试的补丁来支持开发。

贡献

运行单元测试套件：python -m pytest tests/。有关通过 MCP 接口进行的可选 Core/Knots 检查，请参阅真实节点集成测试。

欢迎贡献。请参阅 CONTRIBUTING.md 了解指南，包括如何添加新工具以及 PR 检查清单。

请私下报告安全漏洞——详见 SECURITY.md。

关于

bitcoin-mcp 由 Andrew Barnes 创建并维护，通过 Model Context Protocol 连接 AI Agent 与 Bitcoin 基础设施。

相关项目：

• Satoshi API — Bitcoin 费用情报 API，提供 108 个端点，可用作兼容的可自托管后端
• ChainPulse — AI 驱动的 Bitcoin 网络情报 CLI
• BAIP-1 — Bitcoin Agent 身份协议
• bitcoin-fee-observatory — 费用市场分析仪表板

许可证

MIT