aibtc-mcp-server

Bitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.

- Bitcoin L1- Check balances, send BTC, manage UTXOs via mempool.space
- Agent's Own Wallet- Agents get their own wallet to perform blockchain transactions
- Secure Storage- Wallets encrypted with AES-256-GCM and stored locally
- 150+ Tools- Bitcoin L1 + comprehensive Stacks L2 operations
- sBTC Support- Native Bitcoin on Stacks operations
- Token Operations- SIP-010 fungible token transfers and queries
- NFT Support- SIP-009 NFT holdings, transfers, and metadata
- DeFi Trading- ALEX DEX swaps and Zest Protocol lending/borrowing
- Stacking/PoX- Stacking status and delegation
- BNS Domains- .btc domain lookups and management (V1 + V2)
- x402 Payments- Automatic payment handling for paid APIs

That's it! This automatically configures Claude Code. Restart your terminal and start chatting.

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 withanyMCP-compatible client. Claude Code is the default--installtarget; 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 anOpenRoutermodel 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 fromOpenRouter'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...?"

# 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..."

npx @aibtc/mcp-server@latest --install --testnet # Claude Code, testnet npx @aibtc/mcp-server@latest --install --cursor --testnet # Cursor, testnet

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

VS Code(.vscode/mcp.json) — uses aserverskey 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 acontext_serverskey:

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

Cline / Roo Code(VS Code extension) — add the samemcpServersJSON block above via the extension's MCP settings panel (the exactcline_mcp_settings.jsonpath varies by OS and VS Code build).

Any other MCP client works too — point it atnpx -y @aibtc/mcp-server@latestover stdio withNETWORKin the env.

When you first use @aibtc/mcp-server, Claude doesn't have a wallet. Here's the smooth onboarding flow:

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...

- By default, the wallet auto-locks after 15 minutes
- You can change this withwallet_set_timeout(set to 0 to disable)
- Usewallet_lockto manually lock the wallet
- Usewallet_unlockwhen you need Claude to transact again

Claude'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)

- AES-256-GCM encryption with Scrypt key derivation
- Password required to unlock
- Mnemonics never stored in plaintext
- File permissions set to owner-only (0600)

Each wallet automatically derives both aStacks addressand aBitcoin addressfrom the same mnemonic using BIP39/BIP32 standards.

- Mainnet:m/84'/0'/0'/0/0(Bitcoin coin type 0)
- Testnet:m/84'/1'/0'/0/0(Bitcoin testnet coin type 1)

- Mainnet:bc1q...(Native SegWit P2WPKH)
- Testnet:tb1q...(Native SegWit P2WPKH)

- Full Bitcoin L1 transaction support (send BTC)
- Balance and UTXO queries via mempool.space API
- Fee estimation (fast/medium/slow)
- P2WPKH (native SegWit) transactions for optimal fees

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 officialalex-sdkfor 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 tohuman units(amountUnit: "human"). Pass"2"to swap 2 STX, not"2000000". SetamountUnit: "base"only when working with raw on-chain integers. SeeUnits & Decimals guidefor details and common pitfalls.

Note on spending limits:A default-on safety rail meters every outbound spend (transfer_stx,transfer_btc, x402/L402 auto-payments) 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 and reports the remaining budget. Raise the caps via the env vars above, or disable withSPEND_LIMIT_ENABLED=false. SeeSECURITY.md.

Note:CLIENT_MNEMONICis optional. The recommended approach is to let Claude create its own wallet.HIRO_API_KEYis optional but recommended for production use — without it, you may hit Hiro's public rate limits (429 responses). Get a key atplatform.hiro.so.

You ←→ Claude ←→ aibtc-mcp-server ↓ Claude's Wallet (~/.aibtc/) ↓ ┌─────────┴─────────┐ ↓ ↓ Hiro Stacks API x402 Endpoints ↓ ↓ Stacks Blockchain Paid API Services

- Claude's wallet is stored encrypted on YOUR machine
- Password is never stored - only the encrypted keystore
- Mnemonics shown only once at creation
- Auto-lock after 15 minutes (configurable)
- Transactions signed locally before broadcast
- Spending limit (default-on):outbound spends are capped per session and per day so a single bad instruction can't drain the wallet — seeConfiguration
- Secret-scanning pre-commit hook:contributors get a hook (auto-installed vianpm install) that blocks committing a seed phrase or private key
- For mainnet: Fund with small amounts first

SeeSECURITY.mdfor the full wallet-key protection model and key-leak recovery steps.

{ "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 anAgent Skillscompatible skill that teaches any LLM how to use the Bitcoin wallet capabilities effectively.

- Local:node_modules/@aibtc/mcp-server/skill/SKILL.md
- ClawHub:clawhub.ai/skills- search foraibtc-bitcoin-wallet

skill/ ├── SKILL.md # Bitcoin L1 core workflows └── references/ ├── 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

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 usesRelease Pleasefor automated releases:
- Merge PRs with conventional commits (feat:,fix:, etc.)
- Release Please creates a Release PR with changelog
- Merge the Release PR to publish

To obtain a ClawHub API token, visitclawhub.aiand create an account.

MCP server for dry-run EVM transaction simulation via Crypto APIs