BTCPay Server MCP

xyz.draket由 draket.xyz 发布v0.3.0更新于 Oct 24, 2026

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

已验证STDIO仅桌面金融商业与电商

概览

AI 生成的概览

让助手管理 BTCPay Server 商户账户：创建发票、跟踪付款，并处理商店、Webhook、闪电网络和钱包数据。

可以做什么
通过 BTCPay Server Greenfield REST API 提供 21 个工具。读取类工具涵盖服务器信息、商店、支付方式、发票、拉取付款、打款、付款请求、Webhook、闪电节点信息与通道、钱包余额与交易以及汇率。写入类工具可创建发票、拉取付款、付款请求和 Webhook，并可对发票退款。它以 stdio 方式在本地运行，面向商户收款处理，而非区块链数据或节点 RPC。
适用场景
当助手需要操作 BTCPay Server 商户账户时使用：开具发票、查询付款状态、列出商店与支付方式、设置付款链接或 Webhook，或查看闪电网络与链上钱包数据。它是对区块链数据类服务器的补充，而非替代。
运行要求
需要本地 Python 3.10+ 运行环境，可通过 pip 安装或用 uvx 运行。需要可访问的 BTCPay Server 实例，以及权限合适的 API 密钥，通过环境变量 BTCPAY_BASE_URL、BTCPAY_API_KEY 和 BTCPAY_STORE_ID 提供。需要能访问该服务器的网络。未设置基础地址时默认指向公开的测试网演示实例。
安装前请注意
BTCPAY_API_KEY 中的 API 密钥可访问真实收款账户，应限制其权限并避免放入共享配置。多个工具会写入或涉及资金相关记录：create_invoice、create_pull_payment、create_payment_request、create_webhook 和 refund_invoice。钱包与闪电网络工具会暴露余额和交易历史。请确认基础地址指向预期的服务器，因为默认值是公开的测试网演示实例。

安装

在 SourceWeft 中

  1. 打开 控制台中的 BTCPay Server MCP，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：README.md，提交 a87de3b

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.3.0最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分