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.

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

Top Use Cases

Ask your AI agent:

Configuration

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:

• 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

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_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