{
  "markdown": "# btcpay-mcp\n\n[![PyPI](https://img.shields.io/pypi/v/btcpay-mcp)](https://pypi.org/project/btcpay-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n\nMCP 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/).\n\n**21 tools** · **MIT licensed** · **Zero hardcoded credentials**\n\n> 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.\n\n```bash\npip install btcpay-mcp\n```\n\n## Quick Start\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"btcpay-server\": {\n      \"command\": \"uvx\",\n      \"args\": [\"btcpay-mcp\"],\n      \"env\": {\n        \"BTCPAY_BASE_URL\": \"https://your-btcpay-server.com\",\n        \"BTCPAY_API_KEY\": \"your-api-key\",\n        \"BTCPAY_STORE_ID\": \"your-store-id\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add btcpay-server -- uvx btcpay-mcp\n```\n\n### Cursor / VS Code\n\nAdd to `.cursor/mcp.json` or `.vscode/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"btcpay-server\": {\n      \"command\": \"uvx\",\n      \"args\": [\"btcpay-mcp\"],\n      \"env\": {\n        \"BTCPAY_BASE_URL\": \"https://your-btcpay-server.com\",\n        \"BTCPAY_API_KEY\": \"your-api-key\",\n        \"BTCPAY_STORE_ID\": \"your-store-id\"\n      }\n    }\n  }\n}\n```\n\n### Manual / pip install\n\n```bash\npip install btcpay-mcp\n\n# Set environment variables\nexport BTCPAY_BASE_URL=\"https://your-btcpay-server.com\"\nexport BTCPAY_API_KEY=\"your-api-key\"\nexport BTCPAY_STORE_ID=\"your-store-id\"\n\n# Run\nbtcpay-mcp\n```\n\nOr with pip install from source:\n\n```bash\ngit clone https://github.com/toplyrnarfur/btcpay-mcp.git\n# or: git clone https://codeberg.org/toplyr-narfur/btcpay-mcp.git\ncd btcpay-mcp\npip install -e \".[dev]\"\npython -m btcpay_mcp.server\n```\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_server_info` | BTCPay Server version, sync status, supported methods |\n| `list_stores` | List all stores accessible with the API key |\n| `get_store_info` | Store configuration: currency, speed policy, checkout type |\n| `get_store_payment_methods` | Enabled payment methods: on-chain, Lightning, etc. |\n| `create_invoice` | Create a new invoice (amount, currency, order ID, description) |\n| `get_invoice` | Invoice status, payments received, metadata, timing |\n| `list_invoices` | List invoices with optional status filter |\n| `get_exchange_rate` | Current BTC/fiat exchange rate from BTCPay |\n| `list_pull_payments` | List pull payments (donations, subscriptions, payroll) |\n| `create_pull_payment` | Create pull payment for donations, subscriptions, or payroll |\n| `list_payouts` | List actual payout transactions (claims against pull payments) |\n| `list_payment_requests` | List payment requests (reusable payment links) |\n| `create_payment_request` | Create a payment request (persistent payment page) |\n| `get_payment_request` | Get payment request details and status |\n| `list_webhooks` | List configured webhooks for payment event notifications |\n| `create_webhook` | Create a webhook for real-time payment notifications |\n| `refund_invoice` | Refund an invoice (creates pull payment) |\n| `get_lightning_info` | Lightning node info: alias, version, peers, channels, balance |\n| `list_lightning_channels` | List Lightning channels with capacity, balances, status |\n| `get_wallet_balance` | On-chain wallet balance (confirmed/unconfirmed) |\n| `list_wallet_transactions` | List on-chain wallet transactions |\n\n## Top Use Cases\n\nAsk your AI agent:\n\n| Prompt | What it does |\n|--------|-------------|\n| \"Create a $50 invoice for Order #1234\" | Generates a BTC/Lightning invoice via BTCPay |\n| \"Show me all unpaid invoices\" | Lists pending invoices across stores |\n| \"What payment methods does my store accept?\" | Checks configured payment methods |\n| \"What's the BTC/USD rate right now?\" | Fetches current exchange rate |\n| \"Show me the status of invoice inv_xxxx\" | Retrieves full invoice details and payment status |\n| \"Set up a $100/month donation pull payment\" | Creates a pull payment for recurring donations |\n| \"Create a payment request for my consulting service\" | Creates a reusable payment link |\n| \"Show me my Lightning node info and balance\" | Fetches LN alias, channels, and balances |\n| \"Check my on-chain wallet balance\" | Gets confirmed/unconfirmed BTC wallet balance |\n| \"Set up a webhook for invoice settlements\" | Creates a webhook for real-time payment notifications |\n| \"Refund invoice inv_xxxx\" | Initiates a refund with configurable calculation method |\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `BTCPAY_BASE_URL` | `https://testnet.demo.btcpayserver.org` | Your BTCPay Server URL |\n| `BTCPAY_API_KEY` | *(empty)* | API key from BTCPay Server |\n| `BTCPAY_STORE_ID` | *(empty)* | Default store ID for invoice operations |\n\n### Creating a BTCPay API Key\n\n1. Navigate to your BTCPay Server instance\n2. Go to **Account → API Keys** or **Store Settings → API Keys**\n3. Create a new API key with appropriate permissions\n4. Note the API key and your store ID\n\n## API Endpoints\n\nAll from the [BTCPay Server Greenfield API v1](https://docs.btcpayserver.org/API/Greenfield/v1/):\n\n- `GET /api/v1/server/info` — server version and info\n- `GET /api/v1/stores` — list stores\n- `GET /api/v1/stores/{storeId}` — store configuration\n- `GET /api/v1/stores/{storeId}/payment-methods` — enabled payment methods\n- `POST /api/v1/stores/{storeId}/invoices` — create invoice\n- `GET /api/v1/stores/{storeId}/invoices` — list invoices\n- `GET /api/v1/stores/{storeId}/invoices/{invoiceId}` — invoice details\n- `GET /api/v1/stores/{storeId}/invoices/{invoiceId}/payment-methods` — payment addresses\n- `POST /api/v1/stores/{storeId}/invoices/{invoiceId}/refund` — refund invoice\n- `GET /api/v1/stores/{storeId}/pull-payments` — list pull payments\n- `POST /api/v1/stores/{storeId}/pull-payments` — create pull payment\n- `GET /api/v1/stores/{storeId}/payouts` — list payouts\n- `GET /api/v1/stores/{storeId}/payment-requests` — list payment requests\n- `POST /api/v1/stores/{storeId}/payment-requests` — create payment request\n- `GET /api/v1/stores/{storeId}/payment-requests/{id}` — payment request details\n- `GET /api/v1/stores/{storeId}/webhooks` — list webhooks\n- `POST /api/v1/stores/{storeId}/webhooks` — create webhook\n- `GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/info` — LN node info\n- `GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/balance` — LN balance\n- `GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/channels` — LN channels\n- `GET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet` — wallet balance\n- `GET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet/transactions` — wallet transactions\n- `GET /api/v1/rates` — exchange rates\n\n## How This Differs from Other Bitcoin MCP Servers\n\n| Feature | btcpay-mcp | bitcoin-mcp (Bortlesboat) |\n|---------|-----------|--------------------------|\n| Invoice creation | ✅ Yes | ❌ No |\n| Store management | ✅ Yes | ❌ No |\n| Payment lifecycle | ✅ Yes | ❌ No |\n| Pull payments | ✅ Yes | ❌ No |\n| Payment requests | ✅ Yes | ❌ No |\n| Webhooks | ✅ Yes | ❌ No |\n| Refunds | ✅ Yes | ❌ No |\n| Lightning node info | ✅ Yes | ❌ No |\n| Wallet management | ✅ Yes | ❌ No |\n| Exchange rates | ✅ Yes (BTCPay) | ✅ Yes (Satoshi API) |\n| Blockchain data | ❌ No | ✅ Yes (49 tools) |\n| Node RPC | ❌ No | ✅ Yes (optional) |\n| Merchant payments | ✅ **Only option** | ❌ No |\n\n`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`.\n\n## Run Tests\n\n```bash\npip install -e \".[dev]\"\npytest tests/ -v\n```\n\nAll 77 tests pass with mock-based testing (no BTCPay instance needed).\n\n## Technical Details\n\n- **Python 3.10+** compatible\n- **FastMCP SDK** (official Anthropic MCP Python SDK)\n- **Authentication**: Bearer token via `BTCPAY_API_KEY` environment variable\n- **Transport**: stdio (for Claude Desktop, Cursor, VS Code, Windsurf, etc.)\n- **Default testnet**: Points to `https://testnet.demo.btcpayserver.org` by default\n\n## License\n\nMIT\n",
  "bytes": 8657,
  "sha": "3d3209edee854cc33f262eb04edfd37f9b2a680ba04e545ef696c3e46eae4c3a",
  "repo_slug": "thomsendrake/btcpay-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_xyz_draket_btcpay_mcp_a5a062aa/readme"
}