@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

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

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.

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

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

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 unlock
• Mnemonics never stored in plaintext
• File permissions set to owner-only (0600)

Bitcoin L1 Support

Each wallet automatically derives both a Stacks address and a Bitcoin address from the same mnemonic using BIP39/BIP32 standards.

Derivation Paths (BIP84):

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

Address Format:

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

Capabilities:

• 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

Example:

You: Create a wallet called "my-wallet"
Claude: I've created a wallet with:
        Stacks address: ST1ABC...
        Bitcoin address: bc1q...