aibtc-mcp-server

# @aibtc/mcp-server

[![npm version](https://img.shields.io/npm/v/@aibtc/mcp-server.svg)](https://www.npmjs.com/package/@aibtc/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## Quick Start

### Claude Code (Terminal)

```bash
npx @aibtc/mcp-server@latest --install
```

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

### Claude Desktop (App)

```bash
npx @aibtc/mcp-server@latest --install --desktop
```

This detects your OS and writes to the correct Claude Desktop config file:

| OS | Config Path |
|----|-------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%/Claude/claude_desktop_config.json` |

Restart Claude Desktop after installing.

### Testnet Mode

Add `--testnet` to either command:

```bash
# Claude Code on testnet
npx @aibtc/mcp-server@latest --install --testnet

# Claude Desktop on testnet
npx @aibtc/mcp-server@latest --install --desktop --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 config file.

**Claude Code** (`~/.claude.json`):

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

**Claude Desktop** (`claude_desktop_config.json` -- see path table above):

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

> **Note:** Claude Desktop requires the `-y` flag in args so npx doesn't prompt for confirmation.

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

| State | What Claude Says | What To Do |
|-------|-----------------|------------|
| No wallet | "I don't have a wallet yet" | Use `wallet_create` or `wallet_import` |
| Locked | "My wallet is locked" | Use `wallet_unlock` with password |
| Ready | "My address is ST..." | Claude can perform transactions |

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

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.

## Available Tools (150+ total)

### Wallet Management
| Tool | Description |
|------|-------------|
| `wallet_create` | Create a new wallet for Claude |
| `wallet_import` | Import an existing wallet for Claude |
| `wallet_unlock` | Unlock Claude's wallet |
| `wallet_lock` | Lock Claude's wallet |
| `wallet_list` | List Claude's available wallets |
| `wallet_switch` | Switch Claude to a different wallet |
| `wallet_delete` | Delete a wallet |
| `wallet_export` | Export wallet mnemonic |
| `wallet_status` | Check if Claude's wallet is ready (includes Stacks and Bitcoin addresses) |
| `wallet_set_timeout` | Set how long wallet stays unlocked |

### Bitcoin L1
| Tool | Description |
|------|-------------|
| `get_btc_balance` | Get BTC balance (total, confirmed, unconfirmed) |
| `get_btc_fees` | Get fee estimates (fast, medium, slow) |
| `get_btc_utxos` | List UTXOs for an address |
| `transfer_btc` | Send BTC to a recipient |
| `get_cardinal_utxos` | UTXOs safe to spend (no inscriptions) |
| `get_ordinal_utxos` | UTXOs containing inscriptions |

### Mempool Watch (Bitcoin)
| Tool | Description |
|------|-------------|
| `get_btc_mempool_info` | Get current Bitcoin mempool statistics (tx count, vsize, fees, fee histogram) |
| `get_btc_transaction_status` | Get confirmation status and details for a Bitcoin transaction by txid |
| `get_btc_address_txs` | Get recent transaction history for a Bitcoin address (last 25 transactions) |

### Bitcoin Inscriptions
| Tool | Description |
|------|-------------|
| `get_taproot_address` | Get wallet's Taproot (P2TR) address |
| `estimate_inscription_fee` | Calculate inscription cost |
| `inscribe` | Create inscription commit transaction |
| `inscribe_reveal` | Complete inscription reveal transaction |
| `get_inscription` | Fetch inscription content from reveal tx |
| `get_inscriptions_by_address` | List inscriptions owned by address |

### PSBT & Ordinals Trading
| Tool | Description |
|------|-------------|
| `psbt_create_ordinal_buy` | Build a buyer-side PSBT for ordinal purchase |
| `psbt_sign` | Sign selected PSBT inputs with active wallet keys |
| `psbt_decode` | Decode PSBT inputs/outputs/signature status |
| `psbt_broadcast` | Finalize

[truncated…]