bitcoin-mcp

MCP server giving AI agents Bitcoin and Lightning superpowers.

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

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

Claude Desktop integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.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 connection string from a compatible wallet (Alby, Mutiny, etc.):

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)

Lightning (requires NWC_CONNECTION_STRING)

L402 (requires NWC_CONNECTION_STRING)

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:

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 — blocks, transactions, addresses, fees, Lightning

• blockchain.info — BTC price ticker

No API keys required for read-only tools.

Development

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.