BTCPay Server MCP
21 tools for AI agents to manage BTCPay Server: invoices, payments, stores, webhooks, Lightning
Open source Open in the app JSON README (API)
About
21 tools for AI agents to manage BTCPay Server: invoices, payments, stores, webhooks, Lightning
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- xyz.draket
- Origin
- official
- Category
- ferramentas
- Transport
- desconhecido
- Version
- 0.3.0
- Last push
- 2026-08-17T15:27:39Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:56
- Updated
- 2026-08-29 04:01:56
- Origin id
xyz.draket/btcpay-mcp
README
# btcpay-mcp
[](https://pypi.org/project/btcpay-mcp/)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
MCP server for [BTCPay Server](https://btcpayserver.org/) — let AI agents create invoices, manage stores, track payments, and check exchange rates through the [Greenfield REST API](https://docs.btcpayserver.org/API/Greenfield/v1/).
**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.
```bash
pip install btcpay-mcp
```
## Quick Start
### Claude Desktop
Add to your `claude_desktop_config.json`:
```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
```bash
claude mcp add btcpay-server -- uvx btcpay-mcp
```
### Cursor / VS Code
Add to `.cursor/mcp.json` or `.vscode/mcp.json`:
```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
```bash
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
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](https://docs.btcpayserver.org/API/Greenfield/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](https://pypi.org/project/bitcoin-mcp/). Use both for complete Bitcoin coverage: blockchain data from `bitcoin-mcp`, payment processing from `btcpay-mcp`.
## Run Tests
```bash
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