BTCPay Server MCP

xyz.draketPublished by draket.xyzv0.3.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Lets an assistant manage a BTCPay Server merchant account: create invoices, track payments, handle stores, webhooks, Lightning and wallet data.

What you can do
Exposes 21 tools over the BTCPay Server Greenfield REST API. Read tools cover server info, stores, payment methods, invoices, pull payments, payouts, payment requests, webhooks, Lightning node info and channels, wallet balances and transactions, and exchange rates. Write tools create invoices, pull payments, payment requests and webhooks, and refund invoices. It runs locally over stdio and is aimed at merchant payment processing rather than blockchain data or node RPC.
When to use it
Use it when an assistant should work with a BTCPay Server merchant account: issuing invoices, checking payment status, listing stores and payment methods, setting up payment links or webhooks, or reviewing Lightning and on-chain wallet figures. It complements blockchain-data servers rather than replacing them.
Requirements
Local Python 3.10+ runtime, installed via pip or run with uvx. Needs a reachable BTCPay Server instance and an API key with suitable permissions, supplied through the environment variables BTCPAY_BASE_URL, BTCPAY_API_KEY and BTCPAY_STORE_ID. Network access to that server is required. Defaults to a public testnet demo instance when no base URL is set.
Before you install
The API key in BTCPAY_API_KEY grants access to a live payment account, so scope its permissions and keep it out of shared configs. Several tools write or move money-related records: create_invoice, create_pull_payment, create_payment_request, create_webhook and refund_invoice. Wallet and Lightning tools expose balances and transaction history. Confirm the base URL points at the intended server, since the default is a public testnet demo.

Installation

In SourceWeft

  1. Open BTCPay Server MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

btcpay-mcp

[PyPI] [License: MIT] [Python 3.10+]

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.

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 variablesexport BTCPAY_BASE_URL="https://your-btcpay-server.com"export BTCPAY_API_KEY="your-api-key"export BTCPAY_STORE_ID="your-store-id"
# Runbtcpay-mcp

Or with pip install from source:

bash
git clone https://github.com/toplyrnarfur/btcpay-mcp.git# or: git clone https://codeberg.org/toplyr-narfur/btcpay-mcp.gitcd btcpay-mcppip install -e ".[dev]"python -m btcpay_mcp.server

Tools

ToolDescription
get_server_infoBTCPay Server version, sync status, supported methods
list_storesList all stores accessible with the API key
get_store_infoStore configuration: currency, speed policy, checkout type
get_store_payment_methodsEnabled payment methods: on-chain, Lightning, etc.
create_invoiceCreate a new invoice (amount, currency, order ID, description)
get_invoiceInvoice status, payments received, metadata, timing
list_invoicesList invoices with optional status filter
get_exchange_rateCurrent BTC/fiat exchange rate from BTCPay
list_pull_paymentsList pull payments (donations, subscriptions, payroll)
create_pull_paymentCreate pull payment for donations, subscriptions, or payroll
list_payoutsList actual payout transactions (claims against pull payments)
list_payment_requestsList payment requests (reusable payment links)
create_payment_requestCreate a payment request (persistent payment page)
get_payment_requestGet payment request details and status
list_webhooksList configured webhooks for payment event notifications
create_webhookCreate a webhook for real-time payment notifications
refund_invoiceRefund an invoice (creates pull payment)
get_lightning_infoLightning node info: alias, version, peers, channels, balance
list_lightning_channelsList Lightning channels with capacity, balances, status
get_wallet_balanceOn-chain wallet balance (confirmed/unconfirmed)
list_wallet_transactionsList on-chain wallet transactions

Top Use Cases

Ask your AI agent:

PromptWhat 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

VariableDefaultDescription
BTCPAY_BASE_URLhttps://testnet.demo.btcpayserver.orgYour 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:

  • 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

Featurebtcpay-mcpbitcoin-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. 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

Source: README.md at commit a87de3b

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts