Btcpayserver MCP

🚀 BTCPayServer模型上下文協議服務器（測試版）

這是一個全面的模型上下文協議（MCP）服務器，用於集成BTCPayServer，提供支付處理、店鋪管理、用戶管理、Webhook處理等工具，並具備完整的API覆蓋。

🚀 快速開始

BTCPayServer MCP服務器提供了一套簡化的工具，用於與BTCPayServer API進行交互。如果你想通過MCP與BTCPayServer API進行最佳交互，可以按照以下步驟操作：

1. 探索：使用get_service_info探索可用的方法

get_service_info(serviceName: "invoices")

2. 瞭解：使用get_method_info瞭解參數要求

get_method_info(serviceName: "invoices", methodName: "create")

3. 執行：使用btcpay_request執行操作

btcpay_request(serviceName: "invoices", methodName: "create", parameters: {storeId: "your-store-id", amount: "10.00", currency: "USD"})

✨ 主要特性

• 提供與BTCPayServer API交互的簡化工具集。
• 支持與Claude Desktop集成。
• 全面覆蓋BTCPayServer的API生態系統，涵蓋支付服務、店鋪管理、用戶與訪問管理等多個方面。
• 提供全面的錯誤處理機制。

📦 安裝指南

1. 克隆此倉庫：

git clone <repository-url>
cd btcpayserver-mcp

2. 安裝依賴：

npm install

3. 構建項目：

npm run build

💻 使用示例

基礎用法

運行MCP服務器

npm start

開發環境運行

npm run dev

高級用法

使用MCP Inspector進行開發和調試

MCP Inspector提供了一個可視化界面用於測試：

# 構建項目
npm run build

# 使用BTCPayServer MCP服務器啟動檢查器
npx @modelcontextprotocol/inspector node dist/index.js

開發工作流程

1. 克隆倉庫
2. 安裝依賴：npm install
3. 啟動開發模式：npm run build
4. 運行服務器：node dist/index.js
5. 使用MCP Inspector測試你的更改

📚 詳細文檔

工具參考

BTCPayServer MCP服務器提供了一套簡化的工具，用於與BTCPayServer API進行交互：

與AI助手集成

Claude Desktop集成

要集成Claude Desktop，將以下配置添加到你的claude_desktop_config.json文件中：

{
  "mcpServers": {
    "btcpayserver-mcp": {
      "command": "node",
      "args": ["path/to/btcpayserver-mcp/dist/index.js"],
      "env": {
        "BTCPAY_BASE_URL": "https://your-btcpay-instance.com",
        "BTCPAY_API_KEY": "your_api_key_here",
        "BTCPAY_STORE_ID": "your_default_store_id"
      }
    }
  }
}

服務目錄

BTCPayServer MCP提供對BTCPayServer完整API生態系統的訪問。查看BTCPayServer API文檔以獲取每個服務的詳細信息：

支付服務

店鋪管理

用戶與訪問管理

集成與自動化

系統

配置

MCP服務器需要以下環境變量：

• BTCPAY_BASE_URL - 你的BTCPayServer實例URL（例如，https://btcpay.example.com）
• BTCPAY_API_KEY - 你的BTCPayServer API密鑰
• BTCPAY_STORE_ID - （可選）操作的默認店鋪ID

設置BTCPayServer API密鑰

1. 登錄到你的BTCPayServer實例
2. 轉到賬戶 → 管理賬戶 → API密鑰
3. 點擊生成密鑰
4. 為你的用例選擇所需的權限：
   • 店鋪管理：btcpay.store.canmodifystoresettings
   • 支付請求：btcpay.store.cancreateinvoice
   • 用戶管理：btcpay.user.canmodifyprofile
   • Webhook：btcpay.store.webhooks.canmodifywebhooks
   • 等等
5. 複製生成的API密鑰

環境設置

在項目根目錄下創建一個.env文件：

BTCPAY_BASE_URL=https://your-btcpay-instance.com
BTCPAY_API_KEY=your_api_key_here
BTCPAY_STORE_ID=your_default_store_id

或者直接設置環境變量：

export BTCPAY_BASE_URL=https://your-btcpay-instance.com
export BTCPAY_API_KEY=your_api_key_here
export BTCPAY_STORE_ID=your_default_store_id

🔧 技術細節

項目結構

src/
├── index.ts              # 主要的MCP服務器實現
├── services/             # BTCPayServer服務實現
│   ├── base-service.ts   # 基礎服務類
│   ├── invoices.ts       # 發票管理
│   ├── payment-requests.ts # 支付請求處理
│   ├── stores.ts         # 店鋪管理
│   ├── webhooks.ts       # Webhook管理
│   └── ...               # 其他服務模塊
├── utils/
│   └── btcpay-client.ts  # BTCPayServer API客戶端
└── types.ts              # TypeScript類型定義

構建

npm run build

開發環境運行

npm run dev

錯誤處理

MCP服務器提供全面的錯誤處理：

• 配置錯誤：缺少環境變量
• API錯誤：BTCPayServer API通信問題
• 驗證錯誤：無效的輸入參數
• 身份驗證錯誤：無效或過期的API密鑰

所有錯誤都經過適當格式化，並返回描述性消息。

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。

⚠️ 重要提示

• API密鑰安全：切勿將API密鑰提交到版本控制中。
• 環境變量：使用安全的環境變量管理。
• Webhook密鑰：始終使用Webhook密鑰進行驗證。
• HTTPS：確保BTCPayServer實例使用HTTPS。
• 權限：對API密鑰權限使用最小權限原則。

💡 使用建議

• 本MCP服務器與BTCPayServer v1.7.0及更高版本兼容，使用官方BTCPayServer REST API v1。
• 如果你在使用過程中遇到問題或有疑問，可以：
  1. 查看BTCPayServer文檔
  2. 查看API參考
  3. 在本倉庫中提交問題

🤝 貢獻

如果你想為這個項目做出貢獻，請按照以下步驟操作：

1. 分叉倉庫
2. 創建功能分支
3. 提交你的更改
4. 將更改推送到分支
5. 創建拉取請求

🛠️ 改進建議

請注意，某些方法可能無法正常工作。如果您發現任何問題，請通過報告需求和提交拉取請求來幫助我們改進。為了與最新的API版本保持同步，我們需要持續更新該項目。