@aibtc/mcp-server
Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.
接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
npx -y @aibtc/[email protected]Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
claude mcp add aibtcdev-aibtc-mcp-server -- npx -y @aibtc/mcp-server@1.17.0在終端機中執行。
{ "mcpServers": { "aibtcdev-aibtc-mcp-server": { "command": "npx", "args": [ "-y", "@aibtc/[email protected]" ] } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
npx @aibtc/mcp-server@latest --install
This configures Claude Code and creates the agent's wallet: it prints the Stacks and Bitcoin addresses, a generated password and the 24-word mnemonic once. Write both down. The mnemonic is stored only encrypted (AES-256-GCM) in ~/.aibtc/ on this machine, and the password is not saved anywhere; the agent asks for it to unlock, and you can change it with wallet_rotate_password. If a wallet for the network already exists it is kept. The wallet is only created when the install runs in an interactive terminal (never into a pipe or CI log). Pass --no-wallet to skip it and create or import one from the agent instead.
Restart your terminal, send a little STX to the printed address, and ask the agent to unlock the wallet and make a paid inference call.
npx @aibtc/mcp-server@latest --install --desktop
This detects your OS and writes to the correct Claude Desktop config file:
Restart Claude Desktop after installing.
This is a standard stdio MCP server, so it works with any MCP-compatible client. Claude Code is the default --install target; select another client with a flag:
npx @aibtc/mcp-server@latest --install --cursor # Cursor
npx @aibtc/mcp-server@latest --install --windsurf # Windsurf
npx @aibtc/mcp-server@latest --install --gemini # Gemini CLI
npx @aibtc/mcp-server@latest --install --codex # OpenAI Codex CLI
npx @aibtc/mcp-server@latest --install --vscode # VS Code (writes ./.vscode/mcp.json)
Each installer merges into the existing config — it won't clobber other servers or settings. Restart the client afterward.
The clients above are MCP hosts — they connect to this server for you. To drive the tools with an OpenRouter model instead, the server ships a built-in bridge: it spawns itself in server mode, exposes the tools to the model as function tools, and runs the tool-call loop. This is the client-side pattern from OpenRouter's MCP cookbook, packaged into the binary.
export OPENROUTER_API_KEY=sk-or-...
npx @aibtc/mcp-server@latest bridge "what's the STX balance of SP3...?"
Safety flags (this server moves real funds, so the bridge defaults to nothing extra and lets you constrain it):
# Preview what a read-only session would expose, no key needed:
npx @aibtc/mcp-server@latest bridge --read-only --list-tools
# Read-only chat, plus one explicitly allowed write tool:
npx @aibtc/mcp-server@latest bridge --read-only --allow transfer_stx "send 1 STX to SP3..."
Before any agent loop runs (and on --list-tools), the bridge prints a compact safety receipt to stderr — network, read-only mode, exposed/write/blocked tool counts, the session spend cap, and the number of known x402 endpoints — so the configured execution boundaries are visible up front. It reports boundaries only; it never claims any value moved.
The allowlist is re-enforced at execution time, so a model can never call a tool outside the exposed set. Any MCP-capable agent framework (@openrouter/agent, OpenAI Agents SDK, Claude Agent SDK) can also point at this server directly — the bridge is for driving it through OpenRouter's raw API without adopting a framework.
Add --testnet to any install command:
npx @aibtc/mcp-server@latest --install --testnet # Claude Code, testnet
npx @aibtc/mcp-server@latest --install --cursor --testnet # Cursor, testnet
Why npx? Using
npx @aibtc/mcp-server@latestensures you always get the newest version automatically. Global installs (npm install -g) won't auto-update.
Every tool definition is loaded into the model's context, so --install writes AIBTC_TOOLS=core: a lean core of 26 tools: wallet (including wallet_rotate_password; wallet_export is in the wallet group so the mnemonic isn't one call away), balances, STX/BTC/sBTC transfers, x402 (list_x402_endpoints, probe_x402_endpoint, execute_x402_endpoint) earning (earning_opportunities, bounty_list/get/submit, identity_register) and inbox auto-reply (inbox_auto_reply, inbox_auto_reply_configure).
Add groups with AIBTC_TOOLS=core,defi,ordinals in the server's env (the core is always included), or load everything with AIBTC_TOOLS=all / --profile full. If AIBTC_TOOLS is not set at all, every tool is loaded, so configs written by earlier versions keep all their tools:
npx @aibtc/mcp-server@latest --install --profile full # writes AIBTC_TOOLS=all
The server's instructions list the groups that are off, so the agent can tell you which one to enable. The OpenRouter bridge starts from the full set and narrows it with its own --read-only/--allow/--block flags.
If you prefer to configure manually, add the following to your client's config file. The -y flag stops npx from prompting for confirmation.
Claude Code / Claude Desktop / Cursor / Windsurf / Gemini CLI — mcpServers JSON:
{
"mcpServers": {
"aibtc": {
"command": "npx",
"args": ["-y", "@aibtc/mcp-server@latest"],
"env": {
"NETWORK": "mainnet"
}
}
}
}
VS Code (.vscode/mcp.json) — uses a servers key and a typed entry:
{
"servers": {
"aibtc": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@aibtc/mcp-server@latest"],
"env": { "NETWORK": "mainnet" }
}
}
}
OpenAI Codex CLI (~/.codex/config.toml) — TOML, not JSON:
[mcp_servers.aibtc]
command = "npx"
args = ["-y", "@aibtc/mcp-server@latest"]
[mcp_servers.aibtc.env]
NETWORK = "mainnet"
Zed (settings.json) — uses a context_servers key:
{
"context_servers": {
"aibtc": {
"source": "custom",
"command": "npx",
"args": ["-y", "@aibtc/mcp-server@latest"],
"env": { "NETWORK": "mainnet" }
}
}
}
Cline / Roo Code (VS Code extension) — add the same mcpServers JSON block above via the extension's MCP settings panel (the exact cline_mcp_settings.json path varies by OS and VS Code build).
Any other MCP client works too — point it at
npx -y @aibtc/mcp-server@latestover stdio withNETWORKin the env.
--install creates a wallet for you (see Quick Start). If you installed with --no-wallet, configured the client by hand, or want another wallet, the agent can create or import one:
You: What's your wallet address?
Claude: I don't have a wallet yet. Would you like to assign me one?
I can either create a fresh wallet or you can import an existing one.
You: Create a new wallet called "agent-wallet"
Claude: What password should I use to protect the wallet?
You: use "secure123password"
Claude: I now have a wallet! My address is ST1ABC...XYZ
IMPORTANT: Please save this recovery phrase securely:
"word1 word2 word3 ... word24"
This phrase will NOT be shown again. It's the only way to recover
the wallet if the password is forgotten.
You: Send 10 STX to ST2DEF...
Claude: Done! I've sent 10 STX to ST2DEF...
Transaction: 0x123...
wallet_set_timeout (set to 0 to disable)wallet_lock to manually lock the walletwallet_unlock when you need Claude to transact againClaude's wallets are stored locally on your machine:
~/.aibtc/
├── wallets.json # Wallet index (names, addresses - no secrets)
├── config.json # Active wallet, settings
└── wallets/
└── [wallet-id]/
└── keystore.json # Encrypted mnemonic (AES-256-GCM + Scrypt)
Security:
Each wallet automatically derives both a Stacks address and a Bitcoin address from the same mnemonic using BIP39/BIP32 standards.
Derivation Paths (BIP84):
m/84'/0'/0'/0/0 (Bitcoin coin type 0)m/84'/1'/0'/0/0 (Bitcoin testnet coin type 1)Address Format:
bc1q... (Native SegWit P2WPKH)tb1q... (Native SegWit P2WPKH)Capabilities:
Example:
You: Create a wallet called "my-wallet"
Claude: I've created a wallet with:
Stacks address: ST1ABC...
Bitcoin address: bc1q...
You: Send 50000 sats to bc1q...
Claude: Done! Transaction broadcast: abc123...
Both addresses are derived from the same recovery phrase, making it easy to manage both Layer 1 (Bitcoin) and Layer 2 (Stacks) assets.
Uses the official alex-sdk for swap operations. Supports simple token symbols like "STX", "ALEX".
Supports 10 assets: sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC
DEX aggregator that routes trades across multiple liquidity sources.
Units: Bitflow tools default to human units (
amountUnit: "human"). Pass"2"to swap 2 STX, not"2000000". SetamountUnit: "base"only when working with raw on-chain integers. See Units & Decimals guide for details and common pitfalls.
sBTC smart wallet with Zest Protocol integration and passkey authentication.
For autonomous agents, use pillar_direct_* tools (no browser needed).
Read-only discovery of onchain agent work on TaskMarket (USDC escrow on Base). The tools are public and anonymous: no wallet, no spend.
Wallet management:
"What's your wallet address?" "Create a wallet for yourself" "Unlock your wallet" "Keep your wallet unlocked for 1 hour"
Check balances:
"How much STX do you have?" "What's your sBTC balance?"
Transfer tokens:
"Send 2 STX to ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM" "Transfer 0.001 sBTC to muneeb.btc"
NFTs:
"What NFTs do you own?" "Send this NFT to alice.btc"
BNS domains:
"What address is satoshi.btc?" "Is myname.btc available?"
DeFi trading (mainnet):
"What pools are available on ALEX?" "Swap 0.1 STX for ALEX" "Get a quote for 100 STX to ALEX" "What assets can I lend on Zest?" "Supply 100 stSTX to Zest" "Borrow 50 aeUSDC from Zest" "Check my Zest position"
x402 endpoints:
"Get trending liquidity pools" "Tell me a dad joke"
Well-known tokens can be referenced by symbol:
ALEX DEX tokens: STX, ALEX, and any token from alex_list_pools
Zest Protocol assets: sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC
Or use any SIP-010 token by contract ID: SP2X...::token-name
Note on NETWORK: The --install command writes NETWORK=mainnet by default (pass --testnet to use testnet). If you omit NETWORK from your config entirely, the runtime fallback is also mainnet.
Note on spending limits: A default-on safety rail meters every STX, sBTC and BTC spend (transfers, contract calls, sponsored transactions, x402/L402 auto-payments, Bitcoin broadcasts, psbt_sign) against a cumulative per-session and per-day cap, so a single bad instruction or a malicious endpoint can't drain the wallet. A spend over the cap is blocked before it is signed or broadcast, and the agent is told to ask you. Raise the caps via the env vars above, or disable with SPEND_LIMIT_ENABLED=false. The limit runs inside the server: it does not contain an agent with shell access to your machine, so keep spend tools out of your client's auto-approve list. See SECURITY.md.
Note: CLIENT_MNEMONIC is optional. The recommended approach is to let Claude create its own wallet. HIRO_API_KEY is optional but recommended for production use — without it, you may hit Hiro's public rate limits (429 responses). Get a key at platform.hiro.so.
Note on Hiro rate limits: without a key, Hiro allowed 20 requests per second and 50 per minute per client when measured on 2026-10-23 (response headers below). The per-minute budget is the one an agent usually exhausts first. A single tool call can make several Hiro requests, so 50 a minute goes quickly in a busy session. Every Hiro response reports both budgets, so you can check the current values yourself:
x-ratelimit-limit-stacks-second: 20
x-ratelimit-remaining-stacks-second: 19
x-ratelimit-limit-stacks-minute: 50
x-ratelimit-remaining-stacks-minute: 49
On a 429 the server waits for Retry-After (60s if Hiro sends none, and at least 1s, 2s, then 4s) and retries up to three times before surfacing a rate-limit error (src/services/hiro-api.ts). Retrying before that time just returns another 429. Hiro can change these limits, so treat the numbers as a snapshot and the headers as the source of truth.
You ←→ Claude ←→ aibtc-mcp-server
↓
Claude's Wallet (~/.aibtc/)
↓
┌─────────┴─────────┐
↓ ↓
Hiro Stacks API x402 Endpoints
↓ ↓
Stacks Blockchain Paid API Services
npm install) that blocks committing a seed phrase or private keySee SECURITY.md for the full wallet-key protection model and key-leak recovery steps.
For automated setups where Claude needs immediate wallet access, add the CLIENT_MNEMONIC environment variable to your MCP server config (in ~/.claude.json for Claude Code, or claude_desktop_config.json for Claude Desktop):
{
"mcpServers": {
"aibtc": {
"command": "npx",
"args": ["@aibtc/mcp-server@latest"],
"env": {
"CLIENT_MNEMONIC": "your twenty four word mnemonic phrase",
"NETWORK": "testnet"
}
}
}
}
This bypasses the wallet creation flow - Claude has immediate access to transact.
This package includes an Agent Skills compatible skill that teaches any LLM how to use the Bitcoin wallet capabilities effectively.
The aibtc-bitcoin-wallet skill provides:
The skill is automatically included when you install the MCP server. Find it at:
node_modules/@aibtc/mcp-server/skill/SKILL.mdaibtc-bitcoin-walletskill/
├── SKILL.md # Bitcoin L1 core workflows
└── references/
├── at-stake.md # El Salvador prediction market & side legions
├── genesis-lifecycle.md # Agent registration & check-in
├── inscription-workflow.md # Bitcoin inscription guide
├── pillar-wallet.md # Pillar smart wallet guide
├── stacks-defi.md # Stacks L2 / DeFi operations
├── troubleshooting.md # Common issues and solutions
└── x402-inbox.md # x402 inbox messaging
git clone https://github.com/aibtcdev/aibtc-mcp-server.git
cd aibtc-mcp-server
npm install
npm run build
npm run dev # Run with tsx (development)
This repo uses Release Please for automated releases:
feat:, fix:, etc.)To obtain a ClawHub API token, visit clawhub.ai and create an account.
MIT
Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.
{ "mcpServers": { "aibtcdev-aibtc-mcp-server": { "command": "npx", "args": [ "-y", "@aibtc/[email protected]" ] } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Aibtc 透過 stdio 在本機執行。
上次檢查時間:2026-11-05。 Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.