内容
# Magpie MCP 服务器
Magpie 模型上下文协议（MCP）服务器，为 AI 代理提供访问 Magpie 支付平台 API 的权限。连接您的 Magpie 账户到 Claude Desktop、OpenClaw 或任何兼容 MCP 的 AI 代理，通过自然对话处理支付、创建结账会话、发送发票和管理支付链接。
## 概述
Magpie MCP 服务器公开了所有四个 Magpie API 作为 AI 就绪工具：
| API | 功能 |
|-----|-------------|
| **支付** | 创建支付来源、处理收费、管理退款 |
| **结账会话** | 创建用于收集支付的主机结账页面 |
| **支付请求** | 通过电子邮件或短信发送发票式支付请求 |
| **支付链接** | 创建和管理可分享的支付链接 |
### 支持的支付方式
- **卡** — 带有 3D 安全认证的信用卡/借记卡
- **GCash** — GCash 数字钱包（菲律宾）
- **Maya / PayMaya** — Maya 数字钱包（菲律宾）
- **QR PH** — QR PH 统一 QR 代码支付（菲律宾）
- **支付宝** — 支付宝国际版
- **银联** — 银联国际版
- **微信支付** — 微信支付
> 并非所有支付方式都可在所有 API 上使用。有关详细信息，请参阅 [按 API 划分的支付方式](#payment-methods-by-api)。
## 入门指南
有两种方法可以连接到 Magpie MCP 服务器：
### 选项 A：托管服务器（推荐）
连接到 Magpie 的托管 MCP 服务器。不需要安装 — 通过浏览器中的 OAuth 流安全设置您的 Magpie API 密钥。
**要求：** Node.js 18+（用于 `mcp-remote`）
**Claude Desktop 配置：**
编辑您的配置文件：
- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"magpie": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.magpie.im/mcp"]
}
}
}
```
重启 Claude Desktop。首次启动时，您的浏览器将打开以完成设置：
1. **注册** — 您的 AI 客户端自动向服务器注册
2. **输入 Magpie API 密钥** — 粘贴您的公共密钥和私钥
3. **授权** — 授予 AI 代理访问您的 Magpie 账户的权限
就这样。您的密钥安全地存储在服务器上。未来启动时，连接将自动建立。
### 选项 B：自托管
在您的机器上本地运行 MCP 服务器。您的 API 密钥作为环境变量提供。
**要求：** Node.js 18+，Magpie API 凭证
**Claude Desktop 配置：**
```json
{
"mcpServers": {
"magpie": {
"command": "npx",
"args": ["-y", "magpie-mcp-server"],
"env": {
"MAGPIE_PUBLIC_KEY": "your_public_key_here",
"MAGPIE_SECRET_KEY": "your_secret_key_here"
}
}
}
}
```
重启 Claude Desktop。服务器将自动启动。
#### 替代方案：全局安装
为了更快启动或离线使用：
```bash
npm install -g magpie-mcp-server
```
然后使用此配置：
```json
{
"mcpServers": {
"magpie": {
"command": "magpie-mcp-server",
"env": {
"MAGPIE_PUBLIC_KEY": "your_public_key_here",
"MAGPIE_SECRET_KEY": "your_secret_key_here"
}
}
}
}
```
## 认证
Magpie 使用双密钥认证系统：
- **公共密钥** (`MAGPIE_PUBLIC_KEY`) — 仅用于创建支付来源。安全用于客户端使用。
- **私钥** (`MAGPIE_SECRET_KEY`) — 用于所有其他操作（收费、结账、发票、链接）。必须保持安全。
MCP 服务器自动为每个操作使用正确的密钥。
**托管模式：** 您的密钥通过基于浏览器的 OAuth 流输入一次，并安全地存储在服务器上。配置文件中没有密钥。
**自托管模式：** 密钥作为环境变量提供在您的 Claude Desktop 配置或 `.env` 文件中。
## 可用工具
服务器提供 33 个工具，分为 6 类。
### 支付来源
| 工具 | 描述 |
|------|-------------|
| `create_source` | 创建支付来源（卡、gcash、maya、bpi、alipay、unionpay、wechat） |
| `get_source` | 通过 ID 检索支付来源详细信息 |
### 客户
| 工具 | 描述 |
|------|-------------|
| `create_customer` | 创建客户记录用于 recurring 收费 |
| `get_customer` | 通过 ID 检索客户详细信息 |
| `update_customer` | 更新客户详细信息（移动、描述、元数据） |
| `get_customer_by_email` | 通过电子邮件地址查找客户 |
| `attach_source_to_customer` | 将支付来源附加到客户 |
| `detach_source_from_customer` | 从客户中删除支付来源 |
### 支付收费
| 工具 | 描述 |
|------|-------------|
| `create_charge` | 使用来源创建支付收费。金额以分表示（例如，5000 = PHP 50.00） |
| `get_charge` | 通过 ID 检索收费详情 |
| `list_charges` | 列出所有收费并分页 |
| `capture_charge` | 捕获先前授权的收费 |
| `void_charge` | 取消授权的收费在捕获之前 |
| `refund_charge` | 退款已捕获的收费（全部或部分） |
| `verify_charge` | 使用确认 ID 和 OTP 验证收费 |
### 结账会话
| 工具 | 描述 |
|------|-------------|
| `create_checkout_session` | 创建具有商品和支付方式的主机结账页面 |
| `get_checkout_session` | 检索结账会话详情 |
| `list_checkout_sessions` | 列出所有结账会话 |
| `expire_checkout_session` | 手动过期活动会话 |
| `capture_checkout_session` | 捕获授权的结账会话 |
### 支付请求
| 工具 | 描述 |
|------|-------------|
| `create_payment_request` | 创建发票式支付请求通过电子邮件或短信发送 |
| `get_payment_request` | 检索支付请求详情 |
| `list_payment_requests` | 列出支付请求并过滤状态（打开、已支付、已作废） |
| `void_payment_request` | 作废支付请求并附上原因 |
| `resend_payment_request` | 重新发送支付请求给客户 |
### 支付链接
| 工具 | 描述 |
|------|-------------|
| `create_payment_link` | 创建具有商品的可分享支付链接 |
| `get_payment_link` | 检索支付链接详情 |
| `list_payment_links` | 列出支付链接并过滤状态（活动、停用） |
| `update_payment_link` | 更新支付链接设置 |
| `activate_payment_link` | 重新激活停用的支付链接 |
| `deactivate_payment_link` | 停用活动支付链接 |
## 可用资源
服务器提供 API 文档和 OpenAPI 模式，AI 代理可以读取以获取上下文：
| URI | 描述 |
|-----|-------------|
| `magpie://api/payments/schema` | 支付 API OpenAPI 规范 |
| `magpie://api/checkout/schema` | 结账会话 API OpenAPI 规范 |
| `magpie://api/requests/schema` | 支付请求 API OpenAPI 规范 |
| `magpie://api/links/schema` | 支付链接 API OpenAPI 规范 |
| `magpie://api/documentation` | 所有 Magpie API 的综合文档 |
## 按 API 划分的支付方式
并非所有支付方式都可在每个 API 上使用：
| 方法 | 支付 | 结账 | 请求 | 链接 |
|--------|----------|----------|----------|-------|
| 卡 | 是 | 是 | 是 | 是 |
| GCash | 是 | 是 | 是 | 是 |
| Maya / PayMaya | 是 | 是 | 是 | 是 |
| BPI | 是 | 是 | — | — |
| 支付宝 | 是 | 是 | — | — |
| 银联 | 是 | 是 | — | — |
| 微信支付 | 是 | 是 | — | — |
| QR PH | 是 | — | — | — |
## 示例用法
连接后，您可以通过与 AI 代理的自然对话来与 Magpie 交互：
### 创建结账会话
> "为名为 'Premium Plan' 的产品创建结账会话，价格为 PHP 999.00。接受 GCash 和卡支付。完成后重定向到 https://mysite.com/success。"
AI 代理将使用正确的参数调用 `create_checkout_session`，并返回结账 URL。
### 发送支付请求
> "向 customer@email.com 发送发票，金额为 PHP 2,500.00，用于 'Website Design Services'。通过电子邮件发送。"
代理将调用 `create_payment_request` 并返回支付请求详情。
### 创建支付链接
> "为 'Monthly Subscription' 创建支付链接，价格为 PHP 499.00 每月。接受卡和 Maya。"
代理将调用 `create_payment_link` 并返回可分享的 URL。
### 检查支付状态
> "收费 chr_abc123 的状态是什么？"
代理将调用 `get_charge` 并报告收费是否为待处理、已支付、退款等。
### 退款支付
> "从收费 chr_abc123 中退款 PHP 200.00。"
代理将调用 `refund_charge` 并部分退款。
## 配置参考
对于自托管模式，可用以下环境变量：
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `MAGPIE_PUBLIC_KEY` | 是 | — | Magpie 公共 API 密钥 |
| `MAGPIE_SECRET_KEY` | 是 | — | Magpie 私钥 |
| `MAGPIE_TEST_MODE` | 否 | `false` | 启用测试模式 |
| `MAGPIE_PAYMENTS_BASE_URL` | 否 | `https://api.magpie.im` | 支付 API 基本 URL |
| `MAGPIE_CHECKOUT_BASE_URL` | 否 | `https://api.pay.magpie.im` | 结账 API 基本 URL |
| `MAGPIE_REQUESTS_BASE_URL` | 否 | `https://request.magpie.im/api` | 支付请求 API 基本 URL |
| `MAGPIE_LINKS_BASE_URL` | 否 | `https://buy.magpie.im/api` | 支付链接 API 基本 URL |
您也可以在项目目录中创建一个 `.env` 文件并包含这些值。
## 故障排除
### Claude Desktop 未显示 Magpie 工具
- 确保您在更新配置后完全重启了 Claude Desktop
- 检查配置 JSON 语法是否有效（无尾随逗号，正确的引用）
- 对于 npx：确保您在首次运行时具有互联网连接
- 检查 Claude Desktop 日志中的错误消息
### "命令未找到" 错误
- 验证已安装 Node.js 18+：`node --version`
- 对于 npx 问题，请尝试改为全局安装
- 在 macOS 上使用 NVM，请在配置中使用 npx 的完整路径：
```json
{
"command": "/Users/yourname/.nvm/versions/node/v22.16.0/bin/npx",
"args": ["-y", "magpie-mcp-server"],
"env": {
"PATH": "/Users/yourname/.nvm/versions/node/v22.16.0/bin:/usr/bin:/bin"
}
}
```
### 托管服务器：OAuth 流未完成
- 删除缓存的身份验证状态并重试：`rm -rf ~/.mcp-auth/`
- 检查您的浏览器是否未阻止来自 `localhost` 的弹出窗口
- 如果重定向不起作用，请尝试使用不同的浏览器
### API 认证错误
- 验证您的 Magpie API 凭证是否有效且活跃
- 检查您是否使用正确的测试/实时模式
- 对于托管模式：通过删除 `~/.mcp-auth/` 并重新连接重新输入您的密钥
### 支付处理错误
- 金额以 **分** 为单位（例如，5000 = PHP 50.00）
- 检查您正在使用的 API 是否支持支付方式
- 为开发测试启用测试模式
- 查看错误消息 — 服务器返回 Magpie API 的具体详情
## 许可证
MIT 许可证 — 有关详细信息，请参阅 LICENSE 文件。
## 支持
- **MCP 服务器问题**：[GitHub 问题](https://github.com/domdanao/magpie-mcp-server/issues)
- **Magpie API 问题**：[support@magpie.im](mailto:support@magpie.im)
