# BTCPay Server MCP [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/ThomsenDrake/btcpay-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/btcpay-server-mcp

## Description
21 tools for AI agents to manage BTCPay Server: invoices, payments, stores, webhooks, Lightning

## Tools
Capabilities this server exposes over MCP:

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "btcpay-server-mcp": {
    "command": "uvx",
    "args": ["btcpay-mcp"],
    "env": {
      "BTCPAY_BASE_URL": "",
      "BTCPAY_API_KEY": "",
      "BTCPAY_STORE_ID": ""
    }
  }
}
```

**Requires environment variables:** `BTCPAY_BASE_URL`, `BTCPAY_API_KEY`, `BTCPAY_STORE_ID` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What the BTCPay Server MCP MCP server does

BTCPay Server MCP MCP server gives an MCP-compatible agent access to merchant operations in BTCPay Server. It uses the Greenfield REST API and provides 21 tools covering store inspection, invoice workflows, payment links, payouts, refunds, Lightning information, wallet activity, webhooks, and exchange rates.

The server can create invoices with an amount, currency, order ID, and description, then retrieve individual invoice status, received payments, metadata, and timing. Agents can also filter invoice listings by status. Store-oriented tools expose accessible stores, store configuration, and enabled on-chain or Lightning payment methods.

Payment operations include pull payments for donations, subscriptions, or payroll; payment requests for reusable payment pages; payout listings; and invoice refunds. A refund creates a pull payment. Webhook tools list existing hooks and create new ones for payment event notifications.

## How it works

The BTCPay Server MCP MCP server runs as a Python MCP process and communicates with clients over stdio. Requests from the agent are translated into calls to BTCPay Server’s Greenfield API v1. Authentication uses a bearer token supplied through `BTCPAY_API_KEY`.

Additional tools expose operational data from configured payment infrastructure. Lightning tools return node information, including alias, version, peers, channels, and balance, while channel listings include capacity, balances, and status. Wallet tools report confirmed and unconfirmed on-chain balances and list wallet transactions. The exchange-rate tool retrieves the current BTC-to-fiat rate from BTCPay Server.

The server does not provide general blockchain data or node RPC access. Its scope is BTCPay merchant payment processing and related store infrastructure.

## Setup and configuration

Install the package with `pip install btcpay-mcp`, or run it through `uvx btcpay-mcp`. Configure the MCP client with a command of `uvx`, the package name as its argument, and these environment variables:

- `BTCPAY_BASE_URL`: URL of the BTCPay Server instance. The documented default is the BTCPay testnet demo URL.
- `BTCPAY_API_KEY`: API key created in BTCPay Server under account or store API-key settings.
- `BTCPAY_STORE_ID`: Default store ID used for invoice operations.

The API key must have appropriate permissions for the operations an agent will perform. The README provides configurations for Claude Desktop, Cursor, VS Code, and Claude Code. It also documents direct execution after setting the variables in the shell.

## Tools and capabilities

The BTCPay Server MCP MCP server includes tools for:

- Inspecting server version, synchronization status, supported methods, stores, store settings, and payment methods.
- Creating, retrieving, and listing invoices, including optional status filtering.
- Reading BTC/fiat exchange rates from BTCPay Server.
- Creating and listing pull payments, payouts, payment requests, and webhooks.
- Retrieving payment-request details and creating invoice refunds.
- Inspecting Lightning node information and channel state.
- Reading on-chain wallet balances and transaction history.

Use it for agent-assisted checkout administration, payment-status lookup, recurring or reusable payment flows, payment-event configuration, and operational monitoring of Lightning or wallet data.

## Limitations and notes

The server requires access to a BTCPay Server instance and an API key. Its default URL points to a testnet demonstration instance, but production deployments should set `BTCPAY_BASE_URL` explicitly.

Capabilities depend on the permissions of the configured API key and the payment methods available in the selected store. Refunds are represented by newly created pull payments, and the server is not intended to replace a blockchain-data or Bitcoin node-RPC MCP server.

_Full upstream README: https://allmcps.com/mcp/btcpay-server-mcp/readme_