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 分