Aibtcdev MCP

@aibtc/mcp-server

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

Features

• 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
• 350+ 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-5 - Stake STX with a signer manager, extend, unstake, claim sBTC rewards
• BNS Domains - .btc domain lookups and management (V1 + V2)
• x402 Payments - Automatic payment handling for paid APIs

Quick Start

Claude Code (Terminal)

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.

Claude Desktop (App)

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.

Other MCP Clients

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.

OpenRouter (any model)

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.

Testnet Mode

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@latest ensures you always get the newest version automatically. Global installs (npm install -g) won't auto-update.

Tool Profiles

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.

Manual Configuration

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@latest over stdio with NETWORK in the env.

Giving Claude a Wallet

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

Example Conversation

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 States

Session Management

• By default, the wallet auto-locks after 15 minutes
• You can change this with wallet_set_timeout (set to 0 to disable)
• Use wallet_lock to manually lock the wallet
• Use wallet_unlock when you need Claude to transact again

Wallet Storage

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)

Security:

• AES-256-GCM encryption with Scrypt key derivation
• Password required to unl