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进行交互： | 工具 | 描述 | 主要用途 | |------|-------------|-------------| | get_service_info | 发现服务可用的方法 | 探索和发现 | | get_method_info | 获取详细的参数要求 | 准备请求 | | btcpay_request | 执行对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文档以获取每个服务的详细信息：

支付服务

| 服务 | 描述 | |---------|-------------| | invoices | 创建、管理和跟踪比特币支付发票 | | payment-requests | 创建捐赠或定期账单的支付请求 | | lightning-internal | 管理内部闪电网络操作 | | lightning-store | 店铺级别的闪电网络配置 | | lightning-address | 闪电地址管理和设置 |

店铺管理

| 服务 | 描述 | |---------|-------------| | stores | 店铺创建、配置和管理 | | stores-email | 配置和管理店铺电子邮件设置和SMTP | | stores-payment-methods | 管理店铺可用的支付方式 | | stores-payout-processors | 配置自动支付处理 | | stores-payouts | 管理和处理店铺支付 | | stores-rates | 汇率配置和管理 | | stores-users | 店铺用户访问和权限管理 | | stores-wallet | 店铺钱包管理和操作 |

用户与访问管理

| 服务 | 描述 | |---------|-------------| | users | 用户账户管理和管理 | | api-keys | API密钥创建和权限管理 | | authorization | OAuth和授权流程管理 |

集成与自动化

| 服务 | 描述 | |---------|-------------| | webhooks | 实时事件通知和Webhook管理 | | notifications | 系统通知和警报 | | apps | BTCPayServer应用集成和插件 | | pull-payments | 拉取支付请求和退款管理 |

系统

| 服务 | 描述 | |---------|-------------| | server-info | 服务器状态、版本和配置信息 |

配置

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版本保持同步，我们需要持续更新该项目。