Aibtc MCP Server

🚀 @aibtc/mcp-server

@aibtc/mcp-server 是一个专为 AI 智能体打造的比特币原生 MCP 服务器，支持 BTC/STX 钱包管理、DeFi 收益获取、sBTC 挂钩、NFT 操作以及 x402 支付等功能。

🚀 快速开始

Claude Code（终端）

npx @aibtc/mcp-server@latest --install

完成以上操作后，Claude Code 会自动完成配置。重新启动终端即可开始使用。

Claude Desktop（应用程序）

npx @aibtc/mcp-server@latest --install --desktop

此命令会自动检测你的操作系统，并将配置写入相应的 Claude Desktop 配置文件：

操作系统	配置文件路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json
Windows	%APPDATA%/Claude/claude_desktop_config.json
安装完成后，重启 Claude Desktop。

测试网模式

在上述命令中添加 --testnet 参数：

# Claude Code 测试网模式
npx @aibtc/mcp-server@latest --install --testnet

# Claude Desktop 测试网模式
npx @aibtc/mcp-server@latest --install --desktop --testnet

⚠️ 重要提示

使用 npx @aibtc/mcp-server@latest 可确保你始终自动获取最新版本。全局安装（npm install -g）不会自动更新。

手动配置

如果你希望手动配置，可以在配置文件中添加以下内容。

Claude Code (~/.claude.json)：

{
  "mcpServers": {
    "aibtc": {
      "command": "npx",
      "args": ["@aibtc/mcp-server@latest"],
      "env": {
        "NETWORK": "mainnet"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json，路径见上文表格)：

{
  "mcpServers": {
    "aibtc": {
      "command": "npx",
      "args": ["-y", "@aibtc/mcp-server@latest"],
      "env": {
        "NETWORK": "mainnet"
      }
    }
  }
}

⚠️ 重要提示

Claude Desktop 的配置中，args 需要添加 -y 标志，以避免 npx 提示确认信息。

✨ 主要特性

• 比特币 L1：通过 mempool.space 检查余额、发送 BTC 以及管理 UTXO。
• 智能体专属钱包：智能体拥有自己的钱包，可进行区块链交易。
• 安全存储：钱包使用 AES - 256 - GCM 加密并本地存储。
• 150 + 工具：支持比特币 L1 和全面的 Stacks L2 操作。
• sBTC 支持：支持 Stacks 上的原生比特币操作。
• 代币操作：支持 SIP - 010 可替代代币的转移和查询。
• NFT 支持：支持 SIP - 009 NFT 的持有、转移和元数据查询。
• DeFi 交易：支持 ALEX DEX 交换以及 Zest 协议的借贷操作。
• Stacking/PoX：支持 Stacking 状态查询和委托。
• BNS 域名：支持 .btc 域名的查询和管理（V1 + V2）。
• x402 支付：自动处理付费 API 的支付。

💻 使用示例

钱包管理

"你的钱包地址是什么？" "为你自己创建一个钱包" "解锁你的钱包" "让你的钱包保持解锁状态 1 小时"

检查余额

"你有多少 STX？" "你的 sBTC 余额是多少？"

转移代币

"向 ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM 发送 2 STX" "向 muneeb.btc 转移 0.001 sBTC"

NFT 操作

"你拥有哪些 NFT？" "将这个 NFT 发送给 alice.btc"

BNS 域名操作

"satoshi.btc 的地址是什么？" "myname.btc 是否可用？"

DeFi 交易（主网）

"ALEX 上有哪些可用的交易池？" "用 0.1 STX 交换 ALEX" "获取 100 STX 兑换 ALEX 的报价" "我可以在 Zest 上借出哪些资产？" "向 Zest 存入 100 stSTX" "从 Zest 借入 50 aeUSDC" "检查我在 Zest 的账户状态"

x402 端点操作

"获取热门的流动性池信息" "讲一个爸爸笑话"

📦 安装指南

自动安装

Claude Code

npx @aibtc/mcp-server@latest --install

Claude Desktop

npx @aibtc/mcp-server@latest --install --desktop

测试网模式

# Claude Code 测试网
npx @aibtc/mcp-server@latest --install --testnet

# Claude Desktop 测试网
npx @aibtc/mcp-server@latest --install --desktop --testnet

手动配置

Claude Code (~/.claude.json)

{
  "mcpServers": {
    "aibtc": {
      "command": "npx",
      "args": ["@aibtc/mcp-server@latest"],
      "env": {
        "NETWORK": "mainnet"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "aibtc": {
      "command": "npx",
      "args": ["-y", "@aibtc/mcp-server@latest"],
      "env": {
        "NETWORK": "mainnet"
      }
    }
  }
}

📚 详细文档

为 Claude 分配钱包

首次使用 @aibtc/mcp - server 时，Claude 没有钱包。以下是操作流程：

示例对话

你：你的钱包地址是什么？

Claude：我还没有钱包。你想为我分配一个吗？
        我可以创建一个新钱包，或者你也可以导入一个现有的钱包。

你：创建一个名为 "agent - wallet" 的新钱包

Claude：我应该使用什么密码来保护这个钱包？

你：使用 "secure123password"

Claude：我现在有一个钱包了！我的地址是 ST1ABC...XYZ

        重要提示：请安全保存这个助记词：
        "word1 word2 word3 ... word24"

        这个助记词不会再次显示。如果忘记密码，这是恢复钱包的唯一方式。

你：向 ST2DEF... 发送 10 STX

Claude：已完成！我已向 ST2DEF... 发送了 10 STX
        交易 ID：0x123...

钱包状态

状态	Claude 回复	操作建议
无钱包	"我还没有钱包"	使用 wallet_create 或 wallet_import
锁定	"我的钱包已锁定"	使用 wallet_unlock 并输入密码
就绪	"我的地址是 ST..."	Claude 可以进行交易

会话管理

• 默认情况下，钱包在 15 分钟后自动锁定。
• 你可以使用 wallet_set_timeout 更改锁定时间（设置为 0 可禁用自动锁定）。
• 使用 wallet_lock 手动锁定钱包。
• 需要 Claude 再次进行交易时，使用 wallet_unlock 解锁。

钱包存储

Claude 的钱包存储在本地机器上：

~/.aibtc/
├── wallets.json       # 钱包索引（名称、地址 - 无密钥信息）
├── config.json        # 活动钱包、设置
└── wallets/
    └── [wallet - id]/
        └── keystore.json  # 加密的助记词（AES - 256 - GCM + Scrypt）

⚠️ 重要提示

• 使用 AES - 256 - GCM 加密和 Scrypt 密钥推导。
• 需要密码才能解锁。
• 助记词不会以明文形式存储。
• 文件权限设置为仅所有者可访问（0600）。

比特币 L1 支持

每个钱包会根据 BIP39/BIP32 标准，从相同的助记词自动派生 Stacks 地址 和 比特币地址。

派生路径（BIP84）

• 主网：m/84'/0'/0'/0/0（比特币币种类型 0）
• 测试网：m/84'/1'/0'/0/0（比特币测试网币种类型 1）

地址格式

• 主网：bc1q...（原生隔离见证 P2WPKH）
• 测试网：tb1q...（原生隔离见证 P2WPKH）

功能能力

• 全面支持比特币 L1 交易（发送 BTC）。
• 通过 mempool.space API 查询余额和 UTXO。
• 费用估算（快速/中等/慢速）。
• 支持 P2WPKH（原生隔离见证）交易以优化费用。

示例

你：创建一个名为 "my - wallet" 的钱包
Claude：我已创建一个钱包，信息如下：
        Stacks 地址：ST1ABC...
        比特币地址：bc1q...

你：向 bc1q... 发送 50000 聪
Claude：已完成！交易已广播：abc123...

两个地址从相同的恢复短语派生，便于管理第一层（比特币）和第二层（Stacks）资产。

可用工具（共 150 +）

钱包管理

工具	描述
wallet_create	为 Claude 创建新钱包
wallet_import	为 Claude 导入现有钱包
wallet_unlock	解锁 Claude 的钱包
wallet_lock	锁定 Claude 的钱包
wallet_list	列出 Claude 可用的钱包
wallet_switch	切换 Claude 使用的钱包
wallet_delete	删除钱包
wallet_export	导出钱包助记词
wallet_status	检查 Claude 的钱包是否就绪（包含 Stacks 和比特币地址）
wallet_set_timeout	设置钱包解锁时长

比特币 L1

工具	描述
get_btc_balance	获取 BTC 余额（总余额、已确认余额、未确认余额）
get_btc_fees	获取费用估算（快速、中等、慢速）
get_btc_utxos	列出地址的 UTXO
transfer_btc	向接收方发送 BTC
get_cardinal_utxos	可安全花费的 UTXO（无铭刻）
get_ordinal_utxos	包含铭刻的 UTXO

比特币铭刻

工具	描述
get_taproot_address	获取钱包的 Taproot（P2TR）地址
estimate_inscription_fee	计算铭刻费用
inscribe	创建铭刻提交交易
inscribe_reveal	完成铭刻揭示交易
get_inscription	从揭示交易中获取铭刻内容
get_inscriptions_by_address	列出地址拥有的铭刻

PSBT 与序数交易

工具	描述
psbt_create_ordinal_buy	构建序数购买的买方 PSBT
psbt_sign	使用活动钱包密钥签署选定的 PSBT 输入
psbt_decode	解码 PSBT 输入/输出/签名状态
psbt_broadcast	完成并广播完全签名的 PSBT

消息签名

工具	描述
sip018_sign	签署结构化 Clarity 数据（SIP - 018）
sip018_verify	验证 SIP - 018 签名
sip018_hash	计算 SIP - 018 哈希值而不进行签名
stacks_sign_message	签署纯文本消息（SIWS 兼容）
stacks_verify_message	验证 Stacks 消息签名
btc_sign_message	使用比特币密钥签名（BIP - 137）
btc_verify_message	验证 BIP - 137 签名

钱包与余额

工具	描述
get_wallet_info	获取 Claude 的钱包地址（Stacks + 比特币）和状态
get_stx_balance	获取任何地址的 STX 余额
get_stx_fees	获取 STX 费用估算（低、中、高）

STX 转移

工具	描述
transfer_stx	向接收方发送 STX
broadcast_transaction	广播预签名的交易

sBTC 操作

工具	描述
sbtc_get_balance	获取 sBTC 余额
sbtc_transfer	发送 sBTC
sbtc_initiate_withdrawal	发起 sBTC 向 BTC L1 的提取
sbtc_withdraw	发起提取的别名
sbtc_withdrawal_status	检查提取请求状态
sbtc_get_deposit_info	获取 BTC 存入说明
sbtc_deposit	构建、签名并广播 BTC→sBTC 存入交易
sbtc_deposit_status	通过 Emily API 检查存入状态
sbtc_get_peg_info	获取挂钩比率和总锁定价值

代币操作（SIP - 010）

工具	描述
get_token_balance	获取任何 SIP - 010 代币的余额
transfer_token	发送任何 SIP - 010 代币
get_token_info	获取代币元数据
list_user_tokens	列出地址拥有的代币
get_token_holders	获取代币的前几名持有者

NFT 操作（SIP - 009）

工具	描述
get_nft_holdings	列出地址拥有的 NFT
get_nft_metadata	获取 NFT 元数据
transfer_nft	发送 NFT
get_nft_owner	获取 NFT 所有者
get_collection_info	获取 NFT 集合详情
get_nft_history	获取 NFT 转移历史

Stacking / PoX

工具	描述
get_pox_info	获取当前 PoX 周期信息
get_stacking_status	检查 Stacking 状态
stack_stx	锁定 STX 进行 Stacking
extend_stacking	延长 Stacking 周期

BNS 域名（V1 + V2）

工具	描述
lookup_bns_name	将 .btc 域名解析为地址
reverse_bns_lookup	获取地址对应的 .btc 域名
get_bns_info	获取域名详情
check_bns_availability	检查域名是否可用
get_bns_price	获取注册价格
list_user_domains	列出拥有的域名
preorder_bns_name	预订购 .btc 域名（步骤 1）
register_bns_name	注册 .btc 域名（步骤 2）

智能合约

工具	描述
call_contract	调用智能合约函数
deploy_contract	部署 Clarity 智能合约
get_transaction_status	检查交易状态
call_read_only_function	调用只读函数

DeFi - ALEX DEX（主网）

使用官方 alex - sdk 进行交换操作，支持 "STX"、"ALEX" 等简单代币符号。

工具	描述
alex_list_pools	发现所有可用的交易池
alex_get_swap_quote	获取代币交换的预期输出
alex_swap	执行代币交换（SDK 处理路由）
alex_get_pool_info	获取流动性池储备

DeFi - Zest 协议（主网）

支持 10 种资产：sBTC、aeUSDC、stSTX、wSTX、USDH、sUSDT、USDA、DIKO、ALEX、stSTX - BTC

工具	描述
zest_list_assets	列出所有支持的借贷资产
zest_get_position	获取用户的供应/借贷头寸
zest_supply	存入资产以获取利息
zest_withdraw	提取存入的资产
zest_borrow	抵押借贷
zest_repay	偿还借贷资产

DeFi - Bitflow DEX（主网）

DEX 聚合器，可跨多个流动性来源路由交易。

⚠️ 重要提示

Bitflow 工具默认使用 人类可读单位 (amountUnit: "human")。传递 "2" 表示交换 2 STX，而不是 "2000000"。仅在处理原始链上整数时设置 amountUnit: "base"。详情和常见问题请参考 [单位与小数指南](skill/references/stacks - defi.md#units--decimals - bitflow--defi)。 | 工具 | 描述 | |------|-------------| | bitflow_get_ticker | 获取市场数据（无需 API 密钥） | | bitflow_get_quote | 获取交换报价 | | bitflow_swap | 执行代币交换 |

Pillar 智能钱包

集成 Zest 协议并支持密码钥匙认证的 sBTC 智能钱包。

工具	描述
pillar_connect	连接到 Pillar 钱包
pillar_send	向 BNS 名称或地址发送 sBTC
pillar_boost	创建杠杆 sBTC 头寸
pillar_position	查看钱包和 Zest 头寸
对于自主智能体，可使用 pillar_direct_* 工具（无需浏览器）。

区块链查询

工具	描述
get_account_info	获取账户随机数、余额
get_account_transactions	列出交易历史
get_block_info	获取区块详情
get_mempool_info	获取待处理交易
get_contract_info	获取合约 ABI 和源代码
get_contract_events	获取合约事件历史
get_network_status	获取网络健康状态

收益猎手（自主）

工具	描述
yield_hunter_start	启动自主 sBTC→Zest 存入
yield_hunter_stop	停止收益狩猎
yield_hunter_status	检查收益猎手状态
yield_hunter_configure	调整阈值、储备、间隔

x402 API 端点

工具	描述
list_x402_endpoints	发现 x402 端点
execute_x402_endpoint	执行 x402 端点并自动支付
scaffold_x402_endpoint	生成 x402 Cloudflare Worker 项目
scaffold_x402_ai_endpoint	生成 x402 AI API 与 OpenRouter

支持的代币

知名代币可以使用符号引用：

• sBTC：Stacks 上的原生比特币
• USDCx：Stacks 上的 USD Coin
• ALEX：ALEX 治理代币
• wSTX：包装后的 STX

ALEX DEX 代币：STX、ALEX 以及 alex_list_pools 中的任何代币。

Zest 协议资产：sBTC、aeUSDC、stSTX、wSTX、USDH、sUSDT、USDA、DIKO、ALEX、stSTX - BTC

也可以使用任何 SIP - 010 代币的合约 ID：SP2X...::token - name

配置

环境变量	描述	默认值
NETWORK	mainnet 或 testnet	mainnet（安装程序）/ testnet（未设置时）
API_URL	默认 x402 API 基础 URL	https://x402.biwas.xyz
CLIENT_MNEMONIC	（可选）预配置的助记词	-
HIRO_API_KEY	（可选）Hiro API 密钥，用于提高速率限制	-

⚠️ 重要提示

--install 命令默认写入 NETWORK = mainnet（传递 --testnet 可使用测试网）。如果配置中完全省略 NETWORK，运行时默认使用 testnet。大多数用户应明确设置此变量。

💡 使用建议

CLIENT_MNEMONIC 是可选的。推荐让 Claude 创建自己的钱包。HIRO_API_KEY 是可选的，但建议在生产环境中使用，否则可能会达到 Hiro 的公共速率限制（429 响应）。可在 platform.hiro.so 获取密钥。

架构

你 ←→ Claude ←→ aibtc - mcp - server
                        ↓
              Claude 的钱包 (~/.aibtc/)
                        ↓
              ┌─────────┴─────────┐
              ↓                   ↓
        Hiro Stacks API    x402 端点
              ↓                   ↓
        Stacks 区块链  付费 API 服务

安全注意事项

• Claude 的钱包加密存储在你的机器上。
• 密码不会被存储，仅存储加密的密钥库。
• 助记词仅在创建时显示一次。
• 15 分钟后自动锁定（可配置）。
• 交易在广播前在本地签名。
• 主网使用时，先小额充值。

高级：预配置助记词

对于需要 Claude 立即访问钱包的自动化设置，可在 MCP 服务器配置中添加 CLIENT_MNEMONIC 环境变量（Claude Code 的 ~/.claude.json 或 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "aibtc": {
      "command": "npx",
      "args": ["@aibtc/mcp-server@latest"],
      "env": {
        "CLIENT_MNEMONIC": "your twenty four word mnemonic phrase",
        "NETWORK": "testnet"
      }
    }
  }
}

这样可以绕过钱包创建流程，Claude 可以立即进行交易。

智能体技能

此包包含一个与 Agent Skills 兼容的技能，可教会任何大语言模型有效使用比特币钱包功能。

技能说明

aibtc - bitcoin - wallet 技能提供：

• 比特币 L1 操作的结构化工作流（余额、发送、费用）。
• Pillar 智能钱包和 Stacks L2 DeFi 的参考指南。
• 与 Claude Code、Cursor、Codex 等 20 + 种工具兼容的大语言模型无关指令。

使用技能

安装 MCP 服务器时会自动包含该技能，可在以下位置找到：

• 本地：node_modules/@aibtc/mcp - server/skill/SKILL.md
• ClawHub：clawhub.ai/skills - 搜索 aibtc - bitcoin - wallet

技能结构

skill/
├── SKILL.md                        # 比特币 L1 核心工作流
└── references/
    ├── genesis - lifecycle.md        # 智能体注册与签到
    ├── inscription - workflow.md     # 比特币铭刻指南
    ├── pillar - wallet.md            # Pillar 智能钱包指南
    ├── stacks - defi.md              # Stacks L2 / DeFi 操作
    └── troubleshooting.md          # 常见问题及解决方案

🔧 技术细节

开发

git clone https://github.com/aibtcdev/aibtc - mcp - server.git
cd aibtc - mcp - server
npm install
npm run build
npm run dev       # 使用 tsx 运行（开发环境）

版本发布

本仓库使用 [Release Please](https://github.com/googleapis/release - please) 进行自动版本发布：

1. 合并带有常规提交信息（feat:、fix: 等）的 PR。
2. Release Please 创建包含更新日志的 Release PR。
3. 合并 Release PR 以发布新版本。

仓库密钥（维护者）

密钥	描述
NPM_TOKEN	@aibtc 作用域的 npm 发布令牌
CLAWHUB_API_TOKEN	ClawHub API 令牌，用于技能发布
要获取 ClawHub API 令牌，请访问 clawhub.ai 并创建账户。

📄 许可证

本项目采用 MIT 许可证。