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.

Terminal

pip install btcpay-mcp

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

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

Terminal

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

Cursor / VS Code

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

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"
      }
    }
  }
}

Manual / pip install

Terminal

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:

bash

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

Navigate to your BTCPay Server instance
Go to Account → API Keys or Store Settings → API Keys
Create a new API key with appropriate permissions
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

Terminal

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