比特币钱包MCP服务器

比特币钱包MCP服务器

⚠️ 警告： 实验。对于有意义的资金来说还不安全。仅与您准备丢失的钱包一起使用。代码没有经过实战测试、审计或强化。本文档涵盖了设置、配置、运行和完整的工具参考。

介绍

此回购是一个单一的 主控程序 将比特币（第1层）和Stacks（第2层）钱包操作作为工具公开的服务器。代理或其他MCP客户端通过stdio连接，以JSON形式传递工具名称和参数，并返回结构化结果。服务器封装了本地Python钱包代码和外部API（mempool.space、Hiro、CoinGecko等）。破坏性行动（发送、签署和广播、部署）支持 dry_run 默认情况下不进行广播。任何键或助记符都不会返回。

它揭示了什么： 两组93个工具。

1. 第1层（比特币）： 地址、余额（已确认和未确认）、UTXO、费用估算、单个和多个收件人发送、扫描、PSBT签名/解码、消息签名/验证、序号/铭文、铭文创建、交易历史和RBF、分类账（比特币应用程序）。
2. 第2层（堆叠）： STX地址和余额、随机数、STX和代币转移、Clarity调用/部署/读取、签名、掉期（Alex、Bitflow、Velar）、sBTC桥接、堆叠、BNS、市场和投资组合数据、Ledger（Stacks应用程序）、具有过滤功能的增强交易查询、内存池监控、区块浏览器、合约事件监控、代币元数据（SIP-10/SIP-9）和网络统计。一个助记符或WIF键驱动两层；堆栈键来自同一种子。

目录

• 介绍
• 概述
• 需求
• 安装
• 配置
• 运行服务器
• 建筑
• 工具参考
  • 第1层（比特币）
    • 核心比特币
    • 序号和铭文
    • 铭文创作和入口
    • 交易和钱包管理
    • 账本硬件钱包（比特币）
  • 第2层（堆叠）
    • 堆叠（STX）
    • 掉期、DeFi和桥接
    • BNS和市场数据
    • 分类账硬件钱包（Stacks）
    • 增强的交易查询
    • Mempool运营
    • 区块浏览器
    • 合同事件监控
    • 令牌元数据
    • 网络统计与健康
• 安全
• 测试
• 故障排除
• 参考
• 相关文件

概述

• 目的： 第1层（比特币）和第2层（堆栈）钱包操作作为具有单一安全接口的MCP工具。
• 设计： 破坏性行动支持 dry_run （默认值 true).响应： { "success": true, ... } 或 { "success": false, "error": "..." }回复中没有按键或助记符。

需求

• python：3.10或更高版本（用于类型提示和运行时）。
• 操作系统：Python及其依赖项（Linux、macOS、Windows）支持的任何平台。Ledger工具需要Ledger设备和USB（或Speculos interface: "tcp").
• 依赖项：列在 requirements.txt；安装 pip install -r requirements.txt （参见 安装).

安装

1. 克隆 回购。如果你没有使用 --recurse-submodules，跑 git submodule update --init foundation.

2. 创建虚拟环境 （推荐）：

   复制

   python3 -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   

3. 安装依赖项:

   复制

   pip install -r requirements.txt
   

4. 配置环境：复制 .env.example 到 .env 并设置至少一个密钥源和网络（请参阅 配置).

5. 可选的：如果你使用回购 run_btc_wallet_mcp.sh，它会更喜欢 ../../execution/venv 当存在时；否则，它将使用 python3 从 PATH.

配置

配置来自 环境变量运行者脚本已加载 .env 从 存储库根目录 （此目录之上两层）。您还可以在shell或MCP主机中设置变量。

关键材料（选择一个）

Stacks（STX）键是使用Stacks路径从同一助记符派生出来的 m/44'/5757'/0'/0/0.

网络与安全

限制（可选）

收费行为

运行服务器

• 包装脚本 （推荐）： run_btc_wallet_mcp.sh 负载 .env 从repo根目录，使用 execution/venv/bin/python3 如果存在其他 python3，通过stdio运行服务器。
• 直接： 设置环境变量 .env，然后运行 python3 bitcoin_wallet_mcp_server.py 从这个目录。

光标MCP配置

增添 .cursor/mcp.json （或您的Cursor MCP配置文件）：

{
  "mcpServers": {
    "bitcoin-wallet": {
      "command": "/absolute/path/to/repo/mcp/btc_wallet/run_btc_wallet_mcp.sh"
    }
  }
}

使用指向您的仓库的绝对路径。服务器位于 mcp/btc_wallet/.放 .env 如果您使用脚本的env加载，请在repo根目录下执行。

建筑

• 入口点: bitcoin_wallet_mcp_server.py单台MCP服务器；注册所有工具并委托给钱包模块。
• 第1层（比特币）模块: bitcoin_wallet.py （地址、账户、余额、发送、PSBT、消息签名、费用、UTXO）； ord_wallet.py （序号和铭文）； inscribe_onramp_wallet.py （题词创作、购买报价）； advanced_wallet.py （交易历史、RBF、钱包网络、增强STX交易查询、网络统计）； ledger_wallet.py （Ledger比特币应用程序）。
• 第2层（堆叠）模块: stx_wallet.py （地址、账户、余额、STX/代币转账、合同、签署）； defi_wallet.py （通过Alex、Bitflow、Velar进行交换；sBTC桥；叠加增强的周期指标）； bns_market_wallet.py （BNS、市场、投资组合）； stx_mempool.py （内存池监测和统计）； stx_explorer.py （区块浏览器查询）； stx_events.py （合同事件监控）； stx_token_metadata.py （SIP-10/SIP-9令牌元数据）； ledger_wallet.py （Ledger Stacks应用程序）。

响应： JSON格式 "success": true 和数据，或 "success": false 和 "error"。密钥和助记符永远不会返回。

工具参考

93工具，按第1层（比特币）和第2层（堆栈）分组。参数和响应形状如下；可选参数可以省略。 dry_run 默认为 BTC_DRY_RUN （通常 true).

第1层（比特币）

比特币链工具：地址、余额、转账、PSBT、消息签名、费用、UTXO、序数、铭文创建、交易管理和分类账（比特币应用程序）。

核心比特币

地址和账户管理、余额、价格、转账、PSBT、消息签名、费用、UTXO。

参数：没有。

示例响应 (btc_get_addresses):

{
  "success": true,
  "addresses": [
    {
      "symbol": "BTC",
      "type": "p2wpkh",
      "address": "bc1q...",
      "publicKey": "02abc...",
      "derivationPath": "m/84'/0'/0'/0/0",
      "label": "bip84_p2wpkh_0"
    }
  ],
  "network": "mainnet"
}

参数：没有。

示例响应 (btc_wallet_get_balance): { "success": true, "balance_btc": "0.12345678", "network": "testnet" }
示例响应 (btc_wallet_get_prices): { "success": true, "usd": "91000.12", "eur": "84000.34" }

参数 （预览）： to_address （必填）， amount_btc 或 amount_eur （需要一个）。
参数 （发送）： to_address （必填）， amount_btc 或 amount_eur （需要一个），可选 max_fee_sats, memo, dry_run.

参数 (btc_send_transfer): recipients （数组 { "address", "amount_sats" })，可选 max_fee_sats, memo, dry_run.
参数 (btc_send_max): to_address （必填），可选 fee_rate, dry_run.
参数 (btc_combine_utxos)：可选 to_address, fee_rate, dry_run.

请求示例 (btc_send_transfer):

{
  "recipients": [
    { "address": "bc1q...", "amount_sats": 50000 },
    { "address": "bc1q...", "amount_sats": 30000 }
  ],
  "dry_run": true
}

示例响应: { "success": true, "txid": "DRYRUN_...", "num_recipients": 2, "dry_run": true, "network": "testnet" }

参数 (btc_sign_psbt): psbt （十六进制或base64），可选 sign_at_index （输入索引数组）， broadcast, dry_run.
参数 (btc_sign_batch_psbt): psbts （PSBT字符串数组），可选 broadcast.
参数 (btc_decode_psbt): psbt.

示例响应 (btc_decode_psbt): { "success": true, "num_inputs": 2, "num_outputs": 3, "total_input_sats": 150000, "has_witness_utxo": true, "is_finalized": false, "size_bytes": 512 }

参数 （签名）： message，可选 protocol (ecdsa |BIP-322）， address_type （例如。 p2wpkh).
参数 （验证）： message, signature, address.

示例响应 （签名）： { "success": true, "signature": "H...", "address": "bc1q...", "message": "Hello, world!", "protocol": "ecdsa" }

参数 (btc_estimate_fee): num_inputs, num_outputs, address_type （例如。 p2wpkh)，可选 fee_tier.

示例响应 (btc_get_fees): { "success": true, "fastest_sat_per_vb": 25, "half_hour_sat_per_vb": 18, "hour_sat_per_vb": 12, "economy_sat_per_vb": 5, "minimum_sat_per_vb": 1, "network": "mainnet", "source": "mempool.space" }

参数 (btc_list_utxos)：可选 address_type, min_value_sats, confirmed_only.
参数 (btc_get_utxo_details): txid, vout.

示例响应 (btc_list_utxos): { "success": true, "utxos": [{ "txid": "...", "vout": 0, "value_sats": 50000, "value_btc": "0.00050000", "confirmed": true, "address": "bc1q...", "address_type": "p2wpkh" }], "count": 1, "total_sats": 50000, "total_btc": "0.00050000" }

序号和铭文

使用Hiro Ordinals API作为铭文数据；主根（P2TR）用于普通存储；P2WPKH用于费用资助。

参数 (ord_get_inscriptions)：可选 offset, limit.
参数 (ord_get_inscription_details): inscription_id.

参数 （发送工具）： transfers （数组 { "address", "inscriptionId" })，可选 dry_run.
参数 (ord_extract_from_utxo): outpoint (txid:vout)，可选 dry_run.
参数 （恢复工具）：可选 dry_run.

铭文创作和入口

参数 (ord_create_inscription): content_type, content （如果是文本或十六进制 content_encoding: hex)，可选 content_encoding, dry_run.
参数 (ord_create_repeat_inscriptions): content_type, contents （数组），可选 dry_run.
参数 (buy_get_providers)：可选 crypto, fiat.
参数 (buy_get_quote): crypto, fiat, fiat_amount （或同等）。

交易和钱包管理

参数 (tx_get_history)：可选 chain (btc | stx | both), limit.
参数 (tx_get_status): txid, chain (btc | stx).
参数 (tx_speed_up, tx_cancel): txid，可选 dry_run.
参数 (wallet_switch_network): network (mainnet | testnet).
参数 (wallet_add_network): name, btc_api_url，以及根据需要的其他端点字段。

账本硬件钱包（比特币）

需要一个通过USB连接的Ledger设备，并打开比特币应用程序。使用 interface: "tcp" 对于Speculos来说。

参数: account （可选）， display （可选，在设备上显示）， interface (hid 或 tcp 对于Speculos）。
参数 （签署PSBT）： psbt, interface.

第2层（堆叠）

Stacks链的工具：STX地址、余额、转账、合约、掉期、sBTC桥接、堆叠、BNS、市场/投资组合数据和分类账（Stacks应用程序）。

堆叠（STX）

密钥来源于 BTC_MNEMONIC 使用路径 m/44'/5757'/0'/0/0Hiro Stacks API用于链数据和广播。

参数 (stx_get_balance)：可选 address.

示例响应 (stx_get_balance): { "success": true, "address": "SP...", "balance_ustx": 5000000, "balance_stx": "5.000000", "fungible_tokens": [...], "non_fungible_tokens": [...] }

参数 (stx_transfer_stx): recipient, amount_ustx，可选 memo, dry_run.
参数 (stx_transfer_sip10_ft): recipient, asset （例如。 SP...contract::token), amount，可选 dry_run.
参数 (stx_transfer_sip9_nft): recipient, asset, asset_id，可选 dry_run.

参数 (stx_call_contract): contract_address, contract_name, function_name, function_args （Clarity文字数组），可选 dry_run.
参数 (stx_deploy_contract): contract_name, clarity_code，可选 dry_run.
参数 (stx_read_contract): contract_address, contract_name, function_name，可选 function_args.

清晰论证示例： u100, i-5, true/false, none, 'SP... （负责人）， 0xDEADBEEF （缓冲器）， "hello" （字符串ascii）。

参数 (stx_sign_message): message.
参数 (stx_sign_structured_message): domain, message （JSON字符串）。
参数 (stx_get_nonce)：可选 address.

掉期、DeFi和桥接

交换协议： 亚历克斯、比特流和维拉尔。使用 protocol 对于报价和配对列表： 亚历克斯 （池和代币价格）， 比特流 （股票代码API）， 舌根音 （Alex代币价格）。 执行： swap_execute 支持 protocol=alex 仅（默认）。对于bitflow或velar，您只能获得报价；要执行，请使用alex协议。Bitflow和Velar的执行可以通过协议sdk添加（例如Velar的@velarprotocol/vear-sdk返回contract-call参数；Bitflow需要它们的sdk或API）。

参数 (swap_get_quote): token_in, token_out, amount，可选 protocol (alex | bitflow | velar，默认值 alex).
参数 (swap_execute): token_in, token_out, amount，可选 min_output, protocol （必须是 alex 用于执行）， dry_run.
参数 (sbtc_bridge_deposit): amount_sats，可选 dry_run.
参数 (sbtc_bridge_withdraw): amount_sats, btc_address，可选 dry_run.
参数 (stx_stack): amount_ustx, pox_address, num_cycles，可选 dry_run.

BNS和市场数据

参数 (bns_lookup): name （例如。 alice.btc).
参数 (bns_get_names): address.
参数 (bns_register): name, namespace （例如。 btc)，可选 dry_run.
参数 (market_get_prices): coins （例如。 ["bitcoin", "blockstack"]).
参数 (market_get_history): coin, days，可选 interval （例如。 daily).
参数 (portfolio_get_collectibles)：可选 limit.

分类账硬件钱包（Stacks）

需要通过USB连接的Ledger设备，并打开Stacks应用程序。使用 interface: "tcp" 对于Speculos来说。

参数 (ledger_get_stx_addresses)：可选 account, display, interface.
参数 (ledger_sign_stx_transaction): tx_hex，可选 derivation_path, interface.

增强的交易查询

高级堆栈事务查询，包括过滤、合约特定查询和内存池包含。使用Hiro /extended/v2/addresses/ 和 /extended/v1/address/ 端点。

参数 (stx_query_transactions)：可选 address, limit, offset, tx_type (token_transfer, contract_call, smart_contract, coinbase, poison_microblock), unanchored （包括内存池）。
参数 (stx_query_transactions_by_contract): contract_id （必填），可选 function_name, limit, offset.

示例响应 (stx_query_transactions): { "success": true, "address": "SP...", "transactions": [{ "txid": "0x...", "tx_type": "token_transfer", "status": "success", "block_height": 150000 }], "total": 42, "tx_type_filter": null, "unanchored": false }

Mempool运营

监控挂起的Stacks事务，查看内存池统计信息，并跟踪丢弃的事务。使用Hiro /extended/v1/tx/mempool/ 端点。

参数 (stx_mempool_list_pending)：可选 address, limit, offset.
参数 (stx_mempool_get_dropped)：可选 limit, offset.

示例响应 (stx_mempool_get_stats): { "success": true, "tx_type_counts": { "token_transfer": 42, "contract_call": 18 }, "tx_simple_fee_averages": { "token_transfer": { "p50": 200 } } }

区块浏览器

按高度、哈希或比特币块关联查询堆栈块。使用Hiro /extended/v2/blocks/ 和 /extended/v2/burn-blocks/ 端点。

参数 (stx_get_recent_blocks)：可选 limit, offset.
参数 (stx_get_block_by_height): height （必填）。
参数 (stx_get_block_by_hash): block_hash （必填，有或没有 0x 前缀）。
参数 (stx_get_stacks_blocks_for_bitcoin_block): bitcoin_height （必填），可选 limit, offset.

示例响应 (stx_get_block_by_height): { "success": true, "height": 150000, "hash": "0x...", "burn_block_height": 935748, "tx_count": 12, "transaction_ids": ["0x..."] }

合同事件监控

跟踪智能合约和地址资产转移发出的事件。使用Hiro /extended/v1/contract/ 和 /extended/v1/address/ 端点。

参数 (stx_get_contract_events): contract_id （必填），可选 limit, offset.
参数 (stx_get_address_asset_events)：可选 address （默认：钱包）， limit, offset.

示例响应 (stx_get_contract_events): { "success": true, "contract_id": "SP...contract", "events": [{ "event_type": "fungible_token_asset", "tx_id": "0x...", "asset_id": "SP...::token", "amount": "1000" }], "total": 5 }

令牌元数据

查询SIP-10可替换和SIP-9不可替换令牌元数据和持有者信息。使用Hiro代币元数据API(/metadata/v1/).

参数 (stx_get_token_metadata): contract_id （必填），可选 token_type (ft 或 nft，默认值： ft).
参数 (stx_get_token_holders): contract_id （必填），可选 limit, offset.

示例响应 (stx_get_token_metadata): { "success": true, "contract_id": "SP...::alex-token", "name": "Alex Token", "symbol": "ALEX", "decimals": 8, "total_supply": "1000000000000" }

网络统计与健康

查询Stacks网络状态、对等信息和链提示详细信息。使用Hiro /v2/info 和 /extended/v1/status 端点。

参数：没有。

示例响应 (stx_get_network_info): { "success": true, "peer_version": 402653189, "burn_block_height": 935748, "stacks_tip_height": 150000, "server_version": "stacks-node 2.5.0" }

安全

• 秘密： 不得在工具响应（密钥、助记符、密码）中返回。
• 破坏性行动： 发送、签名、广播和部署工具支持 dry_run.保持 BTC_DRY_RUN=true 除非你打算广播。之前需要明确确认 dry_run=false.
• 先预览： 发送前使用预览/估计工具（例如。 btc_wallet_preview_transfer, btc_estimate_fee, stx_preview_transfer).
• 限制： 可选的 BTC_MAX_SEND_BTC 和 BTC_MAX_FEE_SATS 上限金额和费用。
• 环境： 保持 .env 超出版本控制和限制权限。运行脚本从repo根目录加载它。

测试

现场单元测试 tests/unit/ 并针对MCP服务器行为和钱包模块：

# From mcp/btc_wallet (this directory) or repo root
python -m pytest mcp/btc_wallet/tests/unit -v

测试模块包括： test_bitcoin_wallet_mcp_server.py, test_stx_wallet_mcp_server.py, test_ord_wallet_mcp_server.py, test_defi_wallet_mcp_server.py, test_phase5ab_mcp_server.py, test_phase5d_mcp_server.py, test_ledger_wallet_mcp_server.py, test_hiro_integration_mcp_server.py分类账测试需要设备或Speculos。

故障排除

参考

• 主控程序: 模型上下文协议.此服务器使用的协议和工具合同。
• 基础: markmhendrickson/基金会共享开发流程和文件惯例。克隆后，运行 git submodule update --init foundation 如果 foundation/ 目录为空。