PayPing

payping-mcp：面向 AI Agent 的 PayPing MCP 服务

让你的 AI Agent 使用 PayPing（پی‌پینگ）商户账户。
一个适用于 PayPing 的非官方 MCP 服务。PayPing 是一家伊朗支付网关和发票服务：
可读取余额、销售额、交易记录、客户、产品、优惠券和发票，并在你确认后创建发票、付款链接和优惠券。可通过 Claude、Cursor 或 Copilot 使用。

面向 AI Agent · 为什么选择它 · 功能 · 快速开始 · 工具 · 安全性 · 故障排除 · 常见问题 · فارسی

面向 AI Agent

• **功能：**面向 PayPing（payping.ir，伊朗）商家账户的非官方 MCP 服务（模型上下文协议）。金额单位为 Toman，日期采用 UTC。
• 安装：uvx payping-mcp（需要 uv 和 Python 3.10+；或运行 pip install payping-mcp）。传输方式：stdio。
• Claude Code：claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcp
• 身份验证：PAYPING_TOKEN（必填，PayPing API 令牌；其权限范围决定可用功能）；PAYPING_MCP_PROXY（可选 HTTP 代理）。
• **访问权限：**此服务会操作用户自己的账户，因此并非只读：包含 15 个读取工具和 6 个创建／发送工具。使用任何创建或发送工具前，请先让用户确认。没有任何工具可以提现、退款、撤销或删除。
• **工具：**共 21 个，名称均以 payping_* 开头。建议从 payping_get_profile、payping_get_balance、payping_get_sales_summary、payping_list_transactions、payping_list_invoices 开始。余额和销售汇总使用 PayPing 可能会拒绝 API 令牌访问的仪表板端点；其他工具仍可正常使用。
• 典型流程：payping_create_customer -> payping_create_invoice -> payping_send_invoice；或者 payping_create_product -> payping_create_payment_link。
• **单位：**Toman（不是 Rial）；日期和时间采用 UTC。
• **适用场景：**用户想在自己的 PayPing 账户中查看或创建发票、付款链接、优惠券、客户或销售数据。
• **不适用场景：**任务涉及收取即时付款、验证或退款，或支付款项；本服务没有相应工具。
• **输出：**精简 JSON；列表最多返回 50 项，并包含 total（通过 offset 翻页）；在不同工具间传递代码（客户、产品、发票）。
• 机器可读信息：server.json；伊朗所有 MCP 服务的目录：iran-mcp（TOOLS.md、servers.json、llms.txt）。

为什么使用

PayPing 面板是为需要逐页点击操作的人设计的。要回答“我这个月卖了多少，哪些付款失败了，还有谁欠我钱？”，需要打开多个页面；创建发票则需要手动填写客户、商品和发送步骤。使用 payping-mcp 后，Agent 只需调用几次工具即可完成：读取数据、起草发票、向你展示详情，并且只有在你同意后才会创建并发送发票。

**你：**为 Ali Rezaei 创建一张发票：2 小时咨询服务，每小时 1,500,000 Toman，并发送。

Agent： 调用 payping_list_customers -> 向你展示发票详情并等待你确认 -> payping_create_invoice -> payping_send_invoice

它会提供公开付款页面链接（https://ppng.ir/v/<invoice code>），并告知你 PayPing 已通过短信／电子邮件发送发票。

所有操作都在你的设备上使用你自己的令牌运行。中间没有托管中继服务。

功能

• **资金：**钱包余额、某个时段的销售总额、交易、单笔付款的实际状态、向银行账户的结算
• **店铺数据：**列出和搜索客户、产品、优惠券及发票
• **收款：**创建客户和带有付款页面链接的发票，或为产品创建可重复使用的付款链接，然后让 PayPing 通过短信/电子邮件发送发票
• **安全设计：**在你的设备上运行，只与 PayPing 通信，创建任何内容前都会征求同意，并且无法提现、退款、撤销付款或删除任何内容

示例提示词：

• “显示我的 PayPing 个人资料。”
• “我的 PayPing 余额是多少？本月卖出了多少？”
• “列出本周收到的付款，并告诉我哪些付款失败了。”
• “哪些发票已逾期？”
• “创建一个名为 Monthly plan、价格为 490,000 Toman 的产品，并提供付款链接。”
• “为 Ali Rezaei 创建一张发票：2 小时咨询，每小时 1,500,000 Toman。创建前先给我看看。”
• 显示本月未付款的发票。
• 我的 PayPing 余额是多少？本月卖出了多少？
• 为产品“月度订阅”创建一个付款链接。
• 显示最近转入我银行账户的结算记录。

快速开始

你需要：

• 一个资料完整的 PayPing 商户账户（PayPing 只会为资料完整的账户批准令牌）
• uv
• 一个 MCP 客户端：Claude Code、Claude Desktop、Cursor、VS Code 或其他客户端

然后：

1. 创建 PayPing 令牌，并等待 PayPing 批准。
2. 将服务添加到 MCP 客户端。
3. 检查是否正常工作。

1. 创建 PayPing 令牌

1. 登录 app.payping.ir。

2. 打开连接（اتصالات）→开发者（توسعه دهندگان）。页面标题为令牌（توکن ها）。

3. 点击新建令牌（توکن جدید）并填写表单：

   字段	填写内容
   测试令牌（توکن تست）	留空即可使用真实账户。
   令牌名称（نام توکن）	任意名称，例如 payping-mcp on my laptop
   允许的 IP（آی‌پی‌های مجاز）	可选。如果填写，请列出你的计算机连接 PayPing 时使用的公网 IP。来自其他 IP 的调用会失败，并返回错误代码 166。
   到期日期（تاریخ انقضا）	令牌停止工作的日期。有效期越短越安全。
   权限范围（دسترسی‌ها）	参见下表。
   说明（توضیحات）	例如：MCP server for AI agents
   短信验证码（رمز پیامکی）	点击发送验证码（ارسال رمز），然后输入 PayPing 发送到你手机上的验证码。

4. 点击新建令牌提交。立即复制令牌：PayPing 只会显示一次。

5. 等待批准。PayPing 工作人员会审核每个新令牌。批准后再等待约 10 分钟；在此之前，令牌会返回 HTTP 401。

权限范围。表单默认选中付款报告（گزارش پرداخت‌ها）和创建付款（ساخت پرداخت）。请移除创建付款：此服务不会使用它。然后添加所需权限：

想要只读 Agent？只选择读取权限范围。届时，创建类工具会返回 HTTP 403，账户中的任何内容都不会发生变化。

2. 将服务添加到 MCP 客户端

将 your-token 替换为你的令牌。

claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcp

{
  "mcpServers": {
    "payping": {
      "command": "uvx",
      "args": ["payping-mcp"],
      "env": { "PAYPING_TOKEN": "your-token" }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "payping-token", "description": "PayPing API token", "password": true }
  ],
  "servers": {
    "payping": {
      "type": "stdio",
      "command": "uvx",
      "args": ["payping-mcp"],
      "env": { "PAYPING_TOKEN": "${input:payping-token}" }
    }
  }
}

codex mcp add payping --env PAYPING_TOKEN=your-token -- uvx payping-mcp

[mcp_servers.payping]
command = "uvx"
args = ["payping-mcp"]

[mcp_servers.payping.env]
PAYPING_TOKEN = "your-token"

{
  "mcpServers": {
    "payping": {
      "command": "uvx",
      "args": ["payping-mcp"],
      "env": { "PAYPING_TOKEN": "your-token" }
    }
  }
}

uvx --from git+https://github.com/sepehr071/payping-mcp payping-mcp

3. 检查是否正常工作

向 Agent 提问："Show my PayPing profile." 你应该会看到自己的 PayPing 用户名。如果看到错误，请在 故障排除中查找。

然后试试功能介绍中的示例提示词。

工具

所有金额单位均为 Toman，所有日期均为 UTC。每次调用最多返回 50 条列表项，并包含 total。

只读（15 个）：

创建和发送（6 个；Agent 必须先征得你的确认）：

工作原理

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  payping-mcp  (runs on your machine, holds PAYPING_TOKEN)
      │
      │  HTTPS (REST, Bearer token, optional proxy)
      ├──────▶  api.payping.ir    (reports, customers, products, coupons, invoices)
      └──────▶  oauth.payping.ir  (profile)

payping-mcp 在本地运行，并使用你自己的令牌调用 PayPing 的 API。中间没有托管服务。它会忽略系统代理设置；如果 GET 请求在 HTTP 429、502 或 503 状态下失败，会在 1 秒后重试一次（创建或发送请求绝不会重试）；不保留缓存，并将每个结果作为一个紧凑的 JSON 块返回，同时省略空字段。

隐私与安全

• 仅在本地运行。 服务在你的计算机上运行，只与 api.payping.ir 和 oauth.payping.ir 通信。没有中继服务，也没有遥测。
• 令牌绝不会泄露。 令牌仅通过 Authorization 标头发送给 PayPing，绝不会出现在工具输出、错误信息或日志中。
• 请像对待密码一样保护令牌。 任何持有令牌的人都可以在其权限范围内使用你的账户。不要提交令牌；请使用 VS Code inputs 或客户端的用户配置。只授予所需的权限范围，并设置到期日期。
• 令牌丢失或泄露了？ 在面板中打开令牌，然后使用 حذف（删除）或 تعویض توکن（更换令牌，即签发新值）。然后更新 MCP 配置。
• 创建前请确认。 创建和发送工具带有 destructiveHint 注解，因此 MCP 客户端会在运行前询问。它们的描述也会告知 Agent 先与你确认详细信息。
• 不会转出资金。 没有工具可以提现、退款、撤销付款或删除任何内容。
• 能够识别提示词注入。 客户名称、描述和备注来自其他人。服务会告知 Agent 将这些内容视为数据，绝不视为指令。

须知

• 使用 Toman，而非 Rial。 PayPing 的所有服务都使用 Toman，所有工具也一样。日期和时间均为 UTC。
• 并非只读。 有六个工具会创建数据或向真实客户发送消息。如果你希望 Agent 只能查看，请使用只读权限范围。
• 限制。 每次调用列表最多返回 50 个条目（限制为 1-50）；使用 offset 翻页。redirect_url 必须使用 https。
• 余额和销售汇总的准确性较低。 payping_get_balance 和 payping_get_sales_summary 使用的是 PayPing 控制面板中的端点，而非公开 API 文档中的端点。如果 PayPing 拒绝 API 令牌使用这些端点，工具错误会说明情况，其他所有工具仍可正常工作。
• 不支持原始付款。 特意不支持原始 POST /v3/pay 付款。这类付款需要你自己的回调服务，并且必须在 10 分钟内调用验证接口，否则 PayPing 会向付款人退款。发票和付款链接则使用 PayPing 自己的付款页面。
• 不支持的操作。 不支持提现、退款、撤销付款、验证原始付款、更新或删除。
• 更改权限范围需要更换令牌。 编辑令牌的网站、返回 URL 或权限范围后，PayPing 只有在使用 تعویض توکن（更换令牌）后才会应用更改。更换后会获得新的令牌值；请将其填入 MCP 配置。
• 代理。 如果你的网络需要代理才能连接 PayPing，请设置 PAYPING_MCP_PROXY。系统代理变量会被有意忽略。

故障排除

npx @modelcontextprotocol/inspector -e PAYPING_TOKEN=your-token uvx payping-mcp

包含 PayPing 跟踪 ID 的错误：请将该 ID 提供给 PayPing 支持团队。

常见问题

波斯语：PayPing MCP 服务

claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcp

开发

git clone https://github.com/sepehr071/payping-mcp && cd payping-mcp
uv sync
uv run ruff check . && uv run ruff format --check .
uv run pytest -q                                   # offline, against a mocked PayPing API
PAYPING_TOKEN=your-token uv run pytest -m live     # read-only calls to the real API

工具位于 src/payping_mcp/reports.py（账户、资金）和 shop.py（客户、产品、优惠券、发票）中； http.py 是唯一的 HTTP 代码。每个工具都是带类型标注的异步函数，并附有说明 Agent 何时应使用它的文档字符串。欢迎提交 Issue 和 PR。

发布：更新 pyproject.toml 和 server.json 中的版本，然后推送一个 v* 标签。GitHub Actions 会运行测试、 发布到 PyPI 和 MCP Registry，并创建 GitHub Release。

相关服务

• iran-mcp：所有伊朗服务 MCP 服务的目录
• bale-mcp：通过 Bale 机器人发送消息；这是该系列中的另一个账户工具
• iran-tax-mcp：伊朗税务数据
• tgju-mcp：来自 TGJU 的美元、黄金、硬币和大宗商品价格
• iran-crypto-mcp：伊朗交易所的加密货币价格

免责声明

本项目为非官方项目，与 PayPing 无关，也未获得其认可。它使用您自己的令牌调用 PayPing 的 API。请遵守 PayPing 的条款。它会操作您自己的账户：请检查 Agent 即将创建或发送的内容。

如果这为您省去了几次点击，点个 Star 有助于其他人发现它。

作者

由 Sepehr Radmard（سپهر رادمرد）构建并维护。欢迎在 LinkedIn 上联系，或在 GitHub 上关注 @sepehr071，了解更多面向伊朗网站的 MCP 服务；这些服务都列在 iran-mcp 中。如果这为你节省了时间，欢迎为仓库点个星，帮助其他人发现它。

许可证

MIT