# BTCPay Server MCP

> BTCPay Server MCP is an open-source MCP server for finance and payments. MCP server letting AI agents manage BTCPay Server invoices, stores, payments and Lightning. It is available on CLI, API and self-hosted.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, API, self-hosted
- **Website:** https://pypi.org/project/btcpay-mcp/
- **Repository:** https://github.com/thomsendrake/btcpay-mcp
- **MCP Registry name:** xyz.draket/btcpay-mcp
- **Categories:** [finance and payments](https://ai-powered.com/categories/finance-and-payments), [crypto and web3](https://ai-powered.com/categories/crypto-and-web3)
- **Listing updated:** 2026-11-18

## About

The README says this server connects AI assistants to a BTCPay Server instance through its Greenfield REST API, so an agent can create invoices, check payment status, look up exchange rates and read store and Lightning node details. It is built on the FastMCP Python SDK and runs over stdio, so it plugs into clients such as Claude Desktop, Cursor and VS Code with a base URL, API key and store ID set as environment variables.

The tool list covers merchant operations: store configuration and payment methods, invoices, pull payments, payment requests, payouts, refunds, webhooks, on-chain wallet balances and Lightning channels. The README positions it as a payment-processing counterpart to blockchain data servers, and recommends running both together for full Bitcoin coverage.

It suits people who already run a BTCPay Server and want an assistant to handle routine billing or reconciliation questions. Because it can create invoices and refunds, the README's API key setup and permission scoping matter. The configuration default points at a public testnet demo server, so production use requires changing the base URL.

## Features

- **Invoice creation and lookup:** Creates invoices with amount, currency, order ID and description, and retrieves invoice status and payments.
- **Store and payment method access:** Lists stores accessible to the API key and shows their currency, speed policy and enabled payment methods.
- **Pull payments and payment requests:** Creates pull payments for donations, subscriptions or payroll and reusable payment request pages.
- **Refunds and webhooks:** Initiates invoice refunds and sets up webhooks for payment event notifications.
- **Lightning and wallet visibility:** Reports Lightning node info, channels and balances, plus on-chain wallet balances and transactions.
- **Exchange rate lookup:** Returns current BTC/fiat exchange rates as reported by BTCPay Server.

## Good for

- Generate a BTC or Lightning invoice for a customer order from a chat prompt
- Check which invoices are still unpaid across stores
- Set up a recurring donation pull payment
- Create a reusable payment request for a service
- Review Lightning channel balances and on-chain wallet totals

## Tools

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

## FAQ

### What credentials does it need?

The README says it needs a BTCPay Server base URL, an API key created in BTCPay, and a default store ID, all set as environment variables.

### Which license does it use?

The README states the project is MIT licensed.

### Which AI clients does it support?

The README gives setup steps for Claude Desktop, Claude Code, Cursor and VS Code, and says it uses stdio transport compatible with Windsurf.

### How many tools does it expose?

The README lists 21 tools, covering stores, invoices, pull payments, payment requests, webhooks, refunds, Lightning and wallet operations.

### Is BTCPay Server MCP free?

Yes. BTCPay Server MCP is open source, so you can use and self-host it for free.

### What are the best alternatives to BTCPay Server MCP?

The closest alternatives to BTCPay Server MCP are Billutant MCP by usefulapi, Braintree MCP by usefulapi, smallinvoice MCP by usefulapi, FreeAgent MCP by usefulapi and Chargebee MCP by usefulapi.

## Where this comes from

- Description: written from the project's README, the project's website and its MCP Registry entry.

## Alternatives

- [Billutant MCP by usefulapi](https://ai-powered.com/mcp/billutant-mcp-by-usefulapi): Billutant MCP by usefulapi is a freemium MCP server for finance and payments.
- [Braintree MCP by usefulapi](https://ai-powered.com/mcp/braintree-mcp-by-usefulapi): Braintree MCP by usefulapi is a freemium MCP server for finance and payments.
- [smallinvoice MCP by usefulapi](https://ai-powered.com/mcp/smallinvoice-mcp-by-usefulapi): smallinvoice MCP by usefulapi is a freemium MCP server for finance and payments.
- [FreeAgent MCP by usefulapi](https://ai-powered.com/mcp/freeagent-mcp-by-usefulapi): FreeAgent MCP by usefulapi is a freemium MCP server for finance and payments.
- [Chargebee MCP by usefulapi](https://ai-powered.com/mcp/chargebee-mcp-by-usefulapi): Chargebee MCP by usefulapi is a freemium MCP server for finance and payments.
- [Billy MCP by usefulapi](https://ai-powered.com/mcp/billy-mcp-by-usefulapi): Billy MCP by usefulapi is a freemium MCP server for finance and payments.
- [inv.bg MCP by usefulapi](https://ai-powered.com/mcp/inv-bg-mcp-by-usefulapi): inv.bg MCP by usefulapi is a freemium MCP server for finance and payments.
- [Modern Treasury MCP by usefulapi](https://ai-powered.com/mcp/modern-treasury-mcp-by-usefulapi): Modern Treasury MCP by usefulapi is a freemium MCP server for finance and payments.

---
Source: https://ai-powered.com/mcp/btcpay-server-mcp
