btcpay-mcp

MCP server for BTCPay Server — let AI agents create invoices, manage stores, track payments, and check exchange rates through the Greenfield REST API.

21 tools · MIT licensed · Zero hardcoded credentials

The only MCP server for BTCPay Server. While other Bitcoin MCP servers cover blockchain data and node RPC, btcpay-mcp is the first to expose full merchant payment processing — invoice creation, store management, pull payments, payment requests, Lightning operations, wallet management, webhooks, and exchange rates — to AI agents.

pip install btcpay-mcp

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "btcpay-server": {
      "command": "uvx",
      "args": ["btcpay-mcp"],
      "env": {
        "BTCPAY_BASE_URL": "https://your-btcpay-server.com",
        "BTCPAY_API_KEY": "your-api-key",
        "BTCPAY_STORE_ID": "your-store-id"
      }
    }
  }
}

Claude Code

claude mcp add btcpay-server -- uvx btcpay-mcp

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "mcpServers": {
    "btcpay-server": {
      "command": "uvx",
      "args": ["btcpay-mcp"],
      "env": {
        "BTCPAY_BASE_URL": "https://your-btcpay-server.com",
        "BTCPAY_API_KEY": "your-api-key",
        "BTCPAY_STORE_ID": "your-store-id"
      }
    }
  }
}

Manual / pip install

pip install btcpay-mcp

# Set environment variables
export BTCPAY_BASE_URL="https://your-btcpay-server.com"
export BTCPAY_API_KEY="your-api-key"
export BTCPAY_STORE_ID="your-store-id"

# Run
btcpay-mcp

Or with pip install from source:

git clone https://github.com/toplyrnarfur/btcpay-mcp.git
# or: git clone https://codeberg.org/toplyr-narfur/btcpay-mcp.git
cd btcpay-mcp
pip install -e ".[dev]"
python -m btcpay_mcp.server

Tools

Tool	Description
get_server_info	BTCPay Server version, sync status, supported methods
list_stores	List all stores accessible with the API key
get_store_info	Store configuration: currency, speed policy, checkout type
get_store_payment_methods	Enabled payment methods: on-chain, Lightning, etc.
create_invoice	Create a new invoice (amount, currency, order ID, description)
get_invoice	Invoice status, payments received, metadata, timing
list_invoices	List invoices with optional status filter
get_exchange_rate	Current BTC/fiat exchange rate from BTCPay
list_pull_payments	List pull payments (donations, subscriptions, payroll)
create_pull_payment	Create pull payment for donations, subscriptions, or payroll
list_payouts	List actual payout transactions (claims against pull payments)
list_payment_requests	List payment requests (reusable payment links)
create_payment_request	Create a payment request (persistent payment page)
get_payment_request	Get payment request details and status
list_webhooks	List configured webhooks for payment event notifications
create_webhook	Create a webhook for real-time payment notifications
refund_invoice	Refund an invoice (creates pull payment)
get_lightning_info	Lightning node info: alias, version, peers, channels, balance
list_lightning_channels	List Lightning channels with capacity, balances, status
get_wallet_balance	On-chain wallet balance (confirmed/unconfirmed)
list_wallet_transactions	List on-chain wallet transactions

Top Use Cases

Ask your AI agent:

Prompt	What it does
"Create a $50 invoice for Order #1234"	Generates a BTC/Lightning invoice via BTCPay
"Show me all unpaid invoices"	Lists pending invoices across stores
"What payment methods does my store accept?"	Checks configured payment methods
"What's the BTC/USD rate right now?"	Fetches current exchange rate
"Show me the status of invoice inv_xxxx"	Retrieves full invoice details and payment status
"Set up a $100/month donation pull payment"	Creates a pull payment for recurring donations
"Create a payment request for my consulting service"	Creates a reusable payment link
"Show me my Lightning node info and balance"	Fetches LN alias, channels, and balances
"Check my on-chain wallet balance"	Gets confirmed/unconfirmed BTC wallet balance
"Set up a webhook for invoice settlements"	Creates a webhook for real-time payment notifications
"Refund invoice inv_xxxx"	Initiates a refund with configurable calculation method

Configuration

Variable	Default	Description
BTCPAY_BASE_URL	https://testnet.demo.btcpayserver.org	Your BTCPay Server URL
BTCPAY_API_KEY	(empty)	API key from BTCPay Server
BTCPAY_STORE_ID	(empty)	Default store ID for invoice operations

Creating a BTCPay API Key

1. Navigate to your BTCPay Server instance
2. Go to Account → API Keys or Store Settings → API Keys
3. Create a new API key with appropriate permissions
4. Note the API key and your store ID

API Endpoints

All from the BTCPay Server Greenfield API v1:

• GET /api/v1/server/info — server version and info
• GET /api/v1/stores — list stores
• GET /api/v1/stores/{storeId} — store configuration
• GET /api/v1/stores/{storeId}/payment-methods — enabled payment methods
• POST /api/v1/stores/{storeId}/invoices — create invoice
• GET /api/v1/stores/{storeId}/invoices — list invoices
• GET /api/v1/stores/{storeId}/invoices/{invoiceId} — invoice details
• GET /api/v1/stores/{storeId}/invoices/{invoiceId}/payment-methods — payment addresses
• POST /api/v1/stores/{storeId}/invoices/{invoiceId}/refund — refund invoice
• GET /api/v1/stores/{storeId}/pull-payments — list pull payments
• POST /api/v1/stores/{storeId}/pull-payments — create pull payment
• GET /api/v1/stores/{storeId}/payouts — list payouts
• GET /api/v1/stores/{storeId}/payment-requests — list payment requests
• POST /api/v1/stores/{storeId}/payment-requests — create payment request
• GET /api/v1/stores/{storeId}/payment-requests/{id} — payment request details
• GET /api/v1/stores/{storeId}/webhooks — list webhooks
• POST /api/v1/stores/{storeId}/webhooks — create webhook
• GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/info — LN node info
• GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/balance — LN balance
• GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/channels — LN channels
• GET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet — wallet balance
• GET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet/transactions — wallet transactions
• GET /api/v1/rates — exchange rates

How This Differs from Other Bitcoin MCP Servers

Feature	btcpay-mcp	bitcoin-mcp (Bortlesboat)
Invoice creation	✅ Yes	❌ No
Store management	✅ Yes	❌ No
Payment lifecycle	✅ Yes	❌ No
Pull payments	✅ Yes	❌ No
Payment requests	✅ Yes	❌ No
Webhooks	✅ Yes	❌ No
Refunds	✅ Yes	❌ No
Lightning node info	✅ Yes	❌ No
Wallet management	✅ Yes	❌ No
Exchange rates	✅ Yes (BTCPay)	✅ Yes (Satoshi API)
Blockchain data	❌ No	✅ Yes (49 tools)
Node RPC	❌ No	✅ Yes (optional)
Merchant payments	✅ Only option	❌ No

btcpay-mcp is complementary to blockchain data servers like bitcoin-mcp. Use both for complete Bitcoin coverage: blockchain data from bitcoin-mcp, payment processing from btcpay-mcp.

Run Tests

pip install -e ".[dev]"
pytest tests/ -v

All 77 tests pass with mock-based testing (no BTCPay instance needed).

Technical Details

• Python 3.10+ compatible
• FastMCP SDK (official Anthropic MCP Python SDK)
• Authentication: Bearer token via BTCPAY_API_KEY environment variable
• Transport: stdio (for Claude Desktop, Cursor, VS Code, Windsurf, etc.)
• Default testnet: Points to https://testnet.demo.btcpayserver.org by default

License

MIT