AI导哈

支付服务协议服务器

Magpie MCP服务器是一个模型上下文协议服务器，为AI代理提供访问Magpie支付平台API的能力，支持处理支付、创建结账会话、发送发票和管理支付链接。

  • by domdanao
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 domdanao/magpie-mcp-server

使用说明

喜鹊MCP服务器

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

概述

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

API 它的作用
支付 创建付款来源、处理费用、管理退款
结账会话 创建用于收款的托管结账页面
付款请求 通过电子邮件或短信发送发票式付款请求
付款链接 创建和管理可共享的支付链接

支持的付款方式

  • 卡 --具有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个类别。

付款来源

工具 说明
create_source 创建支付来源（卡、gcash、maya、bpi、支付宝、银联、微信）
get_source 按ID检索付款来源详细信息

客户

工具 说明
create_customer 为经常性费用创建客户记录
get_customer 按ID检索客户详细信息
update_customer 更新客户详细信息（手机、描述、元数据）
get_customer_by_email 通过电子邮件地址查找客户
attach_source_to_customer 将付款来源附加到客户
detach_source_from_customer 从客户中删除付款来源

支付费用

工具 说明
create_charge 使用来源创建付款费用。金额（以美分计）（例如，5000=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 所有喜鹊API的全面文档

API付款方式

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

方法 付款 结账 请求 链接
卡片 是 是 有 有
GCash 是 是 有 有
Maya/PayMaya 是 是 有 有
BPI 是 是 -- --
支付宝 是 是 -- --
银联 是 是 -- --
微信支付 是 是 -- --
QR PH 是 -- -- --

示例用法

连接后，您可以通过与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 部分退款金额。

配置参考

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

变量 必填 默认 描述
MAGPIE_PUBLIC_KEY 是 - 喜鹊公共API密钥
MAGPIE_SECRET_KEY 是 - 喜鹊秘密API密钥
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不显示喜鹊工具

  • 确保重新启动了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