用于 L1 和 L2 的比特币钱包 MCP 服务器

这个周末，我为比特币钱包搭建了一个 MCP 服务器：人工智能代理可以通过模型上下文协议调用的工具。 repo 公开了第 1 层和第 2 层的 93 个工具。一个助记符驱动这两个工具。

我之前是 Leather 的总经理，这是一个也支持比特币和 Stacks 的加密钱包。在 Leather，我发现面向人的自我托管钱包主要面向那些愿意吸收注意力和复杂性的人（例如 degens 和开发人员）。这意味着关键的卫生、费用意识、确认流程等等。认知负荷使真正的潜在市场变得狭窄。

代理钱包改变了这一点。当主要界面是在策略内推理和执行的代理时，用户仅批准重要的内容。摩擦减少了，真正能掌握自己钥匙的人越来越多。

同样的两条链子。不同的表面。

服务器公开的内容（L1 和 L2 在一个表面）

服务器是单个 MCP 进程。客户端通过 stdio 发送工具名称和 JSON 参数并返回结构化结果。破坏性操作（发送、签名并广播、部署）支持“dry_run”，默认情况下不广播。服务器永远不会返回密钥或助记符。

第 1 层（比特币）

核心比特币：

使用公钥和路径派生 P2PKH、P2SH-P2WPKH、P2WPKH 和 P2TR 的地址。
每种地址类型都有余额的账户（UTXO 数据为 mempool.space）；钱包余额和比特币价格（美元、欧元）。
单个和多个收件人发送（金额以比特币或欧元为单位）；发送前预览转账并估算费用。
扫描（发送最大值）和 UTXO 合并。
PSBT 签名、解码和批量签名；消息签名和验证（ECDSA 传统和 BIP-322）。
mempool.space 的费用等级以及按输入/输出计数和地址类型进行的费用估算。
UTXO 列表，包含过滤器（地址类型、最小值、仅确认）和每个 UTXO 详细信息。

序号和铭文：

列出带有分页的铭文；铭文详细信息（起源、内容类型、卫星序号、稀有性、位置）。
发送铭文（完整的 UTXO 或分割，以便只有铭文的卫星范围发送给接收者）。
从混合 UTXO 中提取序数；从序号地址恢复BTC（清除非记号UTXO）；将支付地址上的序号恢复到主根地址。
创建单个或批量铭文并提供提交/显示费用估算。

交易和钱包管理：

BTC和Stacks的交易历史；单个 tx 的状态。
通过RBF加速待处理的BTC；取消待处理的 BTC（RBF 发送给自己）。
网络配置和 API 端点；切换主网/测试网；添加自定义网络。
列出所有支持的工具名称和描述。

分类帐（比特币应用程序）：

从连接的 Ledger 设备获取 BTC 地址。
使用 Ledger Bitcoin 应用程序签署 PSBT。

第 2 层（堆栈）

相同的助记符派生堆栈键（路径“m/44”/5757“/0”/0/0“）。 Hiro 用于链数据和广播的 Stacks API。

堆栈：

地址和公钥；具有 STX 余额、锁定金额、随机数的账户。
余额包括可替代和不可替代的代币。
STX 传输（micro-STX），带有可选备忘录；预览转账以及费用和余额检查。
通过合约调用进行 SIP-10 可替代和 SIP-9 NFT 传输。
清晰：调用公共函数、部署合约、只读调用。
签名序列化Stacks tx (SIP-30)、签名消息、签名SIP-018结构化数据；随机数和费用估算。
BNS 名称的链上配置文件更新 (schema.org/Person)。
使用过滤器（类型、区块范围、非锚定）并按合约进行交易查询。
内存池：列出待处理的交易、内存池统计数据、删除的交易。
区块浏览器：最近的区块、按高度或哈希计算的区块、给定比特币区块的堆栈区块。
合约事件：合约的事件，或地址的资产事件。
令牌元数据：SIP-10 和 SIP-9 元数据和持有者。
网络信息和健康/状态。

掉期、DeFi 和桥接：

支持的货币对和协议（ALEX、Bitflow、Velar）。
三者的掉期报价（预计产量、利率、费用）；通过 ALEX DEX 执行交换。 Bitflow 和 Velar 支持报价和货币对发现；您可以通过协议 SDK 添加执行（例如 Velar SDK 返回合约调用参数）。
链上活动的交换历史记录。
sBTC 余额和桥接存款/取款信息。
堆叠：当前 PoX 状态、周期信息（剩余区块、完成百分比、预计剩余时间、参与率）、启动单独堆叠、撤销委托。

BNS 和市场数据：

BNS 查找（名称到地址），地址拥有的名称，注册 BNS 名称。
多资产价格（例如 CoinGecko）；用于绘制图表的价格历史记录。
投资组合摘要（BTC + STX 美元）；所有资产和收藏品（铭文、Stacks NFT）。

分类帐（堆栈应用程序）：

从 Ledger 获取 Stacks 地址。
使用 Ledger Stacks 应用程序签署 Stacks 交易。

安全与设计

⚠️ 这个 MCP 服务器是实验性的，对于有意义的资金来说并不安全。仅与您准备丢失的钱包一起使用。没有人对代码进行过实际测试或审核。我将其视为探索代理原生钱包表面的研究工件。

破坏性操作默认为“dry_run: true”。每个发送路径都存在预览和估计工具。密钥不受版本控制和工具响应的影响。运行脚本从存储库根加载“.env”。

钱包关键变量（保密，永不提交）：

BTC_PRIVATE_KEY — WIF 编码的比特币私钥；如果设置，则优先于助记符。
BTC_MNEMONIC — BIP-39 种子短语；服务器使用它来派生比特币和 Stacks 密钥（相同的助记符，Stacks 的路径“m/44”/5757'/0'/0/0）。
BTC_MNEMONIC_PASSPHRASE — 与 BTC_MNEMONIC 一起使用的可选 BIP-39 密码。

安全和限制（env 或 .env）：

BTC_NETWORK — mainnet 或 testnet （默认为 testnet）。
BTC_MAINNET_ENABLED — 设置此项以允许主网发送（安全标志）。
BTC_DRY_RUN — 设置时（默认），破坏性操作（发送、签名和广播、部署）不会广播；将其设置为“false”以允许真实交易。
BTC_MAX_SEND_BTC — 可选的 BTC 发送金额上限；服务器拒绝高于此的请求。
BTC_MAX_FEE_SATS — 每笔交易的可选费用上限（以聪为单位）。
STX_ACCOUNT_INDEX — 堆栈派生帐户索引（默认为“0”）。
配置以其他方式驱动费用等级（固定费率或 mempool.space 等级：小时、半小时、最快）。

它如何适合我的代理堆栈

我在三层架构上运行代理。各层清晰分离，以便记忆、推理和行动保持在正确的位置。

真相层： 这是记忆基板。它保存类型化的结构化数据：资产、流量、交易、联系人、任务等。在我的设置中，规范存储是 Neotoma。它使用事件源和缩减器，具有完整的来源和实体解析。特工们从中读取。他们从不直接写出真相。所有更新都流经执行层生成的域事件。

**战略层：**这是目标、约束和策略所在的层。战略文件、战术手册和操作手册都放在这里。代理使用这一层进行推理：它们读取世界状态，评估优先级和风险，并生成决策和命令。战略是纯粹的认知。无副作用。状态输入，决策输出。

**执行层：**这是外部操作发生的地方。它从策略层获取命令，并通过适配器执行副作用：电子邮件、日历、DNS，在本例中是比特币和 Stacks 钱包 MCP。钱包服务器是众多执行适配器之一。它永远不会改变真相层。它执行任务（发送、签名、交换），堆栈的其余部分记录通过域事件发生的事情。命令输入，事件输出。

我定义并维护该策略。代理从真相层读取数据并调用 MCP 工具来执行。我不使用点击式加密用户界面进行日常操作。我只会介入批准超出我预设限制的行动。

短期来看，我的用例是一次性的：支付服务费用、通过手动提示重新平衡投资组合。从长远来看，我希望这些流程自动化。代理将在策略范围内进行监控、推理和执行。我会看到解释并在需要时批准。

我如何进行构建

我首先在自己的工作流程中对服务器进行测试。我正在通过少量的试运行逐渐测试每个表面（发送、PSBT、序号、堆栈传输、交换）。

我已将其连接到我已经使用真相和策略层的同一堆栈中。代理可以将钱包操作与日历、电子邮件和数据结合起来。外部用户尚不在范围内。

我的目标是验证代理钱包表面的形状，并使我自己的比特币和 Stacks 操作由代理驱动而不是手动。

要运行它：克隆 mcp-server-bitcoin（或在 mcp/btc_wallet/ 作为子模块添加），将服务器添加到您的 MCP 配置中（使用 run_btc_wallet_mcp.sh 脚本路径），并使用试运行的测试钱包。

要点