BTCPay Server MCP

btcpay-mcp

适用于 BTCPay Server 的 MCP 服务——通过 Greenfield REST API，让 AI Agent 创建发票、管理商店、追踪付款并查询汇率。

21 个工具 · MIT 许可 · 零硬编码凭据

唯一适用于 BTCPay Server 的 MCP 服务。其他 Bitcoin MCP 服务专注于区块链数据和节点 RPC，而 btcpay-mcp 首创将完整的商户支付处理——发票创建、商店管理、提取付款、付款请求、Lightning 操作、钱包管理、Webhooks 和汇率——开放给 AI Agent 使用。

pip install btcpay-mcp

快速开始

Claude Desktop

将以下内容添加到 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

将以下内容添加到 .cursor/mcp.json 或 .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"
      }
    }
  }
}

手动安装 / 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

或者使用 pip 从源代码安装：

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

工具

工具	说明
get_server_info	BTCPay Server 版本、同步状态、支持的方法
list_stores	列出 API 密钥可访问的所有商店
get_store_info	商店配置：货币、速度策略、结账类型
get_store_payment_methods	已启用的付款方式：链上、Lightning 等
create_invoice	创建新发票（金额、货币、订单 ID、说明）
get_invoice	发票状态、已收到的付款、元数据、时间信息
list_invoices	列出发票，可按状态筛选
get_exchange_rate	从 BTCPay 获取当前 BTC/法币汇率
list_pull_payments	列出提取付款（捐赠、订阅、薪资）
create_pull_payment	为捐赠、订阅或薪资创建提取付款
list_payouts	列出实际付款交易（针对提取付款发起的领取）
list_payment_requests	列出付款请求（可重复使用的付款链接）
create_payment_request	创建付款请求（持久有效的付款页面）
get_payment_request	获取付款请求的详细信息和状态
list_webhooks	列出为付款事件通知配置的 Webhook
create_webhook	创建用于实时付款通知的 Webhook
refund_invoice	退款发票（创建提取付款）
get_lightning_info	Lightning 节点信息：别名、版本、对等节点、通道、余额
list_lightning_channels	列出 Lightning 通道及其容量、余额和状态
get_wallet_balance	链上钱包余额（已确认 / 未确认）
list_wallet_transactions	列出链上钱包交易

常见用例

向你的 AI Agent 提问：

提示词	功能
“为订单 #1234 创建一张 50 美元的发票”	通过 BTCPay 生成 BTC/Lightning 发票
“显示所有未付款的发票”	列出各商店待处理的发票
“我的商店接受哪些付款方式？”	检查已配置的付款方式
“现在 BTC/USD 汇率是多少？”	获取当前汇率
“显示发票 inv_xxxx 的状态”	获取完整的发票详情和付款状态
“设置每月 100 美元的捐赠提取付款”	创建用于定期捐赠的提取付款
“为我的咨询服务创建付款请求”	创建可重复使用的付款链接
“显示我的 Lightning 节点信息和余额”	获取 LN 别名、通道和余额
“查询我的链上钱包余额”	获取已确认 / 未确认的 BTC 钱包余额
“为发票结算设置 Webhook”	创建用于实时付款通知的 Webhook
“为发票 inv_xxxx 退款”	使用可配置的计算方式发起退款

配置

变量	默认值	描述
BTCPAY_BASE_URL	https://testnet.demo.btcpayserver.org	你的 BTCPay Server URL
BTCPAY_API_KEY	(empty)	来自 BTCPay Server 的 API 密钥
BTCPAY_STORE_ID	(empty)	发票操作的默认商店 ID

创建 BTCPay API 密钥

1. 打开你的 BTCPay Server 实例
2. 前往 账户 → API 密钥 或 商店设置 → API 密钥
3. 创建具有适当权限的新 API 密钥
4. 记下 API 密钥和商店 ID

API 端点

均来自 BTCPay Server Greenfield API v1：

• GET /api/v1/server/info — 服务版本和信息
• GET /api/v1/stores — 列出商店
• GET /api/v1/stores/{storeId} — 商店配置
• GET /api/v1/stores/{storeId}/payment-methods — 已启用的支付方式
• POST /api/v1/stores/{storeId}/invoices — 创建发票
• GET /api/v1/stores/{storeId}/invoices — 列出发票
• GET /api/v1/stores/{storeId}/invoices/{invoiceId} — 发票详情
• GET /api/v1/stores/{storeId}/invoices/{invoiceId}/payment-methods — 支付地址
• POST /api/v1/stores/{storeId}/invoices/{invoiceId}/refund — 退款发票
• GET /api/v1/stores/{storeId}/pull-payments — 列出拉取支付
• POST /api/v1/stores/{storeId}/pull-payments — 创建拉取支付
• GET /api/v1/stores/{storeId}/payouts — 列出付款
• GET /api/v1/stores/{storeId}/payment-requests — 列出支付请求
• POST /api/v1/stores/{storeId}/payment-requests — 创建支付请求
• GET /api/v1/stores/{storeId}/payment-requests/{id} — 支付请求详情
• GET /api/v1/stores/{storeId}/webhooks — 列出 Webhook
• POST /api/v1/stores/{storeId}/webhooks — 创建 Webhook
• GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/info — LN 节点信息
• GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/balance — LN 余额
• GET /api/v1/stores/{storeId}/lightning/{cryptoCode}/channels — LN 通道
• GET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet — 钱包余额
• GET /api/v1/stores/{storeId}/payment-methods/{pmId}/wallet/transactions — 钱包交易
• GET /api/v1/rates — 汇率

与其他 Bitcoin MCP 服务的区别

功能	btcpay-mcp	bitcoin-mcp (Bortlesboat)
创建发票	✅ 是	❌ 否
商店管理	✅ 是	❌ 否
支付生命周期	✅ 是	❌ 否
拉取支付	✅ 是	❌ 否
支付请求	✅ 是	❌ 否
Webhook	✅ 是	❌ 否
退款	✅ 是	❌ 否
Lightning 节点信息	✅ 是	❌ 否
钱包管理	✅ 是	❌ 否
汇率	✅ 是（BTCPay）	✅ 是（Satoshi API）
区块链数据	❌ 否	✅ 是（49 个工具）
节点 RPC	❌ 否	✅ 是（可选）
商户支付	✅ 唯一选择	❌ 否

btcpay-mcp 与 bitcoin-mcp 等区块链数据服务互为补充。结合使用即可完整覆盖 Bitcoin：从 bitcoin-mcp 获取区块链数据，从 btcpay-mcp 处理支付。

运行测试

pip install -e ".[dev]"
pytest tests/ -v

基于模拟的测试中，全部 77 项测试均通过（无需 BTCPay 实例）。

技术详情

• 兼容 Python 3.10+
• FastMCP SDK（Anthropic 官方 MCP Python SDK）
• 身份验证：通过 BTCPAY_API_KEY 环境变量使用 Bearer 令牌
• 传输方式：stdio（适用于 Claude Desktop、Cursor、VS Code、Windsurf 等）
• 默认测试网：默认指向 https://testnet.demo.btcpayserver.org

许可证

MIT