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-mcpis 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
- 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 infoGET /api/v1/stores— list storesGET /api/v1/stores/{storeId}— store configurationGET /api/v1/stores/{storeId}/payment-methods— enabled payment methodsPOST /api/v1/stores/{storeId}/invoices— create invoiceGET /api/v1/stores/{storeId}/invoices— list invoicesGET /api/v1/stores/{storeId}/invoices/{invoiceId}— invoice detailsGET /api/v1/stores/{storeId}/invoices/{invoiceId}/payment-methods— payment addressesPOST /api/v1/stores/{storeId}/invoices/{invoiceId}/refund— refund invoiceGET /api/v1/stores/{storeId}/pull-payments— list pull paymentsPOST /api/v1/stores/{storeId}/pull-payments— create pull paymentGET /api/v1/stores/{storeId}/payouts— list payoutsGET /api/v1/stores/{storeId}/payment-requests— list payment requestsPOST /api/v1/stores/{storeId}/payment-requests— create payment requestGET /api/v1/stores/{storeId}/payment-requests/{id}— payment request detailsGET /api/v1/stores/{storeId}/webhooks— list webhooksPOST /api/v1/stores/{storeId}/webhooks— create webhookGET /api/v1/stores/{storeId}/lightning/{cryptoCode}/info— LN node infoGET /api/v1/stores/{storeId}/lightning/{cryptoCode}/balance— LN balanceGET /api/v1/stores/{storeId}/lightning/{cryptoCode}/channels— LN channelsGET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet— wallet balanceGET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet/transactions— wallet transactionsGET /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_KEYenvironment variable - Transport: stdio (for Claude Desktop, Cursor, VS Code, Windsurf, etc.)
- Default testnet: Points to
https://testnet.demo.btcpayserver.orgby default
License
MIT