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 許可證。