# bitcoin-mcp

MCP server giving AI agents Bitcoin and Lightning superpowers.

```bash
pip install bitcoin-mcp
```

Plug it into Claude Desktop, Cursor, or any MCP-compatible client and your AI can instantly:

- 📈 **Check Bitcoin price** (USD / EUR / GBP)
- ⛏️ **Inspect mempool**, fee rates, blocks, and transactions
- ⚡ **Decode Lightning invoices**
- 🌐 **Query the Lightning Network** global stats
- 👛 **Pay Lightning invoices** via Nostr Wallet Connect (NWC)
- 🔐 **Fetch L402-protected content**, auto-paying the invoice

## Quick start

```bash
pip install bitcoin-mcp
bitcoin-mcp          # starts MCP server on stdio
```

### Claude Desktop integration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bitcoin": {
      "command": "bitcoin-mcp",
      "env": {
        "NWC_CONNECTION_STRING": "nostr+walletconnect://your-nwc-uri-here"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see Bitcoin tools appear in the tool picker.

### Lightning payments (optional)

Requires a [Nostr Wallet Connect](https://nwc.dev) connection string from a
compatible wallet (Alby, Mutiny, etc.):

```bash
export NWC_CONNECTION_STRING="nostr+walletconnect://..."
export NWC_MAX_SATS=5000   # spending cap per payment (default: 10000)
```

Also requires Node.js (`npx`) for the `@getalby/cli` NWC backend.

## Available tools

### Read-only (no auth needed)

| Tool | Description |
|------|-------------|
| `btc_price` | BTC price in USD, EUR, GBP |
| `mempool_info` | Unconfirmed tx count, vsize, fee rates (fastest/hour/economy) |
| `latest_block` | Most recent block: height, hash, timestamp, tx count |
| `get_block` | Block by height or hash |
| `decode_invoice` | Decode a bolt11: amount, description, expiry, payee |
| `lightning_stats` | LN node count, channel count, total capacity |
| `address_info` | On-chain balance (confirmed + unconfirmed) in satoshis |
| `address_txs` | Recent transactions for a Bitcoin address |
| `get_tx` | Transaction details: confirmations, fee, inputs, outputs |

### Lightning (requires `NWC_CONNECTION_STRING`)

| Tool | Description |
|------|-------------|
| `wallet_balance` | Lightning wallet balance in satoshis |
| `pay_invoice` | Pay a bolt11 invoice (capped by `NWC_MAX_SATS`) |
| `create_invoice` | Create a Lightning invoice |

### L402 (requires `NWC_CONNECTION_STRING`)

| Tool | Description |
|------|-------------|
| `fetch_l402` | Fetch an L402-protected URL, auto-paying the Lightning invoice |

## Example session

Once connected, you can ask Claude:

> *"What's the current Bitcoin price and mempool congestion?"*

> *"Decode this invoice: lnbc1000n1p..."*

> *"What's the balance on bc1q...?"*

> *"Pay this invoice for me: lnbc..."* (requires NWC)

## Python API

The library can also be used directly in Python:

```python
import asyncio
from bitcoin_mcp import BitcoinAPIClient, NWCClient

async def main():
    async with BitcoinAPIClient() as api:
        price = await api.get_price()
        print(f"BTC: ${price['usd']:,.0f}")

        mempool = await api.get_mempool_info()
        print(f"Mempool: {mempool['count']:,} txs")
        print(f"Fastest fee: {mempool['fees']['fastest_sat_vb']} sat/vB")

        # Decode an invoice
        decoded = await api.decode_invoice("lnbc1000n1p...")
        print(f"Invoice for {decoded['amount_sat']} sats: {decoded['description']}")

asyncio.run(main())
```

## Data sources

All data is fetched from free public APIs:

- **[mempool.space](https://mempool.space)** — blocks, transactions, addresses, fees, Lightning
- **[blockchain.info](https://blockchain.info/ticker)** — BTC price ticker

No API keys required for read-only tools.

## Development

```bash
git clone https://github.com/spcpza/bitcoin-mcp
cd bitcoin-mcp
pip install -e ".[dev]"
pytest
```

## Support

This is open-source infrastructure for autonomous AI agents. If your agent uses it or you're building on top of it, consider donating:

⚡ `sensiblefield821792@getalby.com`

Issues and PRs welcome.