Magpie MCP Server

喜鹊MCP服务器

一个模型上下文协议（MCP）服务器，允许AI代理访问喜鹊支付平台API。将您的喜鹊帐户连接到Claude Desktop、OpenClaw或任何兼容MCP的AI代理，以通过自然对话处理付款、创建结账会话、发送发票和管理付款链接。

概述

喜鹊MCP服务器将所有四个喜鹊API作为AI就绪工具公开：

支持的付款方式

• 卡 --具有3D安全身份验证的信用卡/借记卡
• GCash --GCash数字钱包（菲律宾）
• 玛雅/帕伊玛雅 --Maya数字钱包（菲律宾）
• QR-PH --QR PH统一二维码支付（菲律宾）
• 支付宝 --支付宝国际
• 银联 --银联国际
• 微信支付 --微信支付

并非所有API都提供所有付款方式。看 API付款方式 了解详情。

入门指南

有两种方法可以连接到喜鹊MCP服务器：

选项A：托管服务器（推荐）

连接到喜鹊托管的MCP服务器。无需安装-您的Magpie API密钥通过浏览器中的OAuth流安全设置。

要求： Node.js 18+（适用于 mcp-remote)

Claude桌面配置：

编辑您的配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "magpie": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.magpie.im/mcp"]
    }
  }
}

重新启动克劳德桌面。首次启动时，您的浏览器将打开以完成设置：

1. 注册 --您的AI客户端会自动向服务器注册
2. 输入Magpie API键 --粘贴您的公钥和私钥
3. 授权 --授予AI代理访问您的喜鹊帐户的权限

就是这样。您的密钥安全地存储在服务器上。在未来的发射中，连接是自动的。

选项B：自托管

在您的计算机上本地运行MCP服务器。您的API密钥是作为环境变量提供的。

要求： Node.js 18+，Magpie API证书

Claude桌面配置：

{
  "mcpServers": {
    "magpie": {
      "command": "npx",
      "args": ["-y", "magpie-mcp-server"],
      "env": {
        "MAGPIE_PUBLIC_KEY": "your_public_key_here",
        "MAGPIE_SECRET_KEY": "your_secret_key_here"
      }
    }
  }
}

重新启动克劳德桌面。服务器自动启动。

替代方案：全局安装

为了更快地启动或离线使用：

npm install -g magpie-mcp-server

然后使用此配置：

{
  "mcpServers": {
    "magpie": {
      "command": "magpie-mcp-server",
      "env": {
        "MAGPIE_PUBLIC_KEY": "your_public_key_here",
        "MAGPIE_SECRET_KEY": "your_secret_key_here"
      }
    }
  }
}

认证

喜鹊使用双密钥身份验证系统：

• 公钥 (MAGPIE_PUBLIC_KEY)--仅用于创建付款来源。客户端使用安全。
• 密钥 (MAGPIE_SECRET_KEY)--用于所有其他操作（收费、结账、发票、链接）。必须保持安全。

MCP服务器自动为每个操作使用正确的密钥。

托管模式： 您的密钥通过基于浏览器的OAuth流输入一次，并安全地存储在服务器上。配置文件中没有密钥。

自托管模式： 密钥作为环境变量提供在Claude Desktop配置或 .env 文件。

可用工具

该服务器提供33个工具，分为6个类别。

付款来源

客户

支付费用

结账会话

付款请求

付款链接

可用资源

服务器提供了API文档和OpenAPI架构，AI代理可以读取这些架构以获取上下文：

API付款方式

并非所有支付方式都适用于每个API：

示例用法

连接后，您可以通过与AI代理的自然对话与喜鹊互动：

创建结账会话

“使用PHP 999.00为名为“高级计划”的产品创建一个结账会话。接受GCash和卡支付。重定向到https://mysite.com/success完成后。"

AI代理将呼叫 create_checkout_session 使用正确的参数并返回结账URL。

发送付款请求

“将发票发送至customer@email.com用于“网站设计服务”的PHP 2500.00。通过电子邮件发送。"

代理人将致电 create_payment_request 通过电子邮件发送并返回付款请求详细信息。

创建付款链接

“以每月499.00 PHP的价格为‘每月订阅’创建付款链接。接受卡和Maya。”

代理人将致电 create_payment_link 并返回可共享的URL。

检查付款状态

“chr_abc123的充电状态如何？”

代理人将致电 get_charge 并报告费用是否待定、已支付、已退还等。

退款

“从收费chr_abc123中退还200.00菲律宾比索。”

代理人将致电 refund_charge 部分退款金额。

配置参考

对于自托管模式，以下环境变量可用：

您还可以创建 .env 使用这些值在项目目录中创建文件。

故障排除

Claude Desktop不显示喜鹊工具

• 确保重新启动了Claude Desktop 完全 更新配置后
• 检查配置JSON语法是否有效（没有尾随逗号，引号正确）
• 对于npx：确保您在首次运行时具有互联网连接
• 检查Claude Desktop日志中的错误消息

“找不到命令”错误

• 验证是否安装了Node.js 18+： node --version
• 对于npx问题，请尝试全局安装方法
• 在带NVM的macOS上，在配置中使用npx的完整路径：

  {
    "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=50.00菲律宾比索）
• 检查您正在使用的API是否支持付款方式
• 启用开发测试的测试模式
• 查看错误消息-服务器从喜鹊的API返回特定详细信息

许可证

MIT许可证——有关详细信息，请参阅许可证文件。

支持

• MCP服务器问题:
• 喜鹊API问题: support@magpie.im