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)

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:

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.