Metadata-Version: 2.4
Name: btcpay-mcp
Version: 0.3.0
Summary: MCP server for BTCPay Server — create invoices, manage pull payments, process Bitcoin/Lightning payments, manage webhooks, monitor Lightning nodes, and track wallet balances via the Greenfield API
Author: Omnis Vir Lupus
License: MIT
Project-URL: Homepage, https://docs.btcpayserver.org/API/Greenfield/v1/
Project-URL: Documentation, https://docs.btcpayserver.org/API/Greenfield/v1/
Project-URL: Bug Tracker, https://codeberg.org/toplyr-narfur/btcpay-mcp/issues
Project-URL: Repository, https://codeberg.org/toplyr-narfur/btcpay-mcp
Keywords: mcp,mcp-server,bitcoin,btcpay,lightning,payment,ai-agent,invoice,merchant,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: requests-mock>=1.11; extra == "dev"
Dynamic: license-file

# btcpay-mcp

[![PyPI](https://img.shields.io/pypi/v/btcpay-mcp)](https://pypi.org/project/btcpay-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](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://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
