PayPing

io.github.sepehr071v0.1.0更新於 Oct 4, 2026

PayPing merchant account for agents: balance, sales, invoices; create invoices and payment links.

已驗證STDIO僅桌面Finance Business & Commerce

概覽

AI 產生的概覽

讓助理讀取 PayPing 商戶帳戶的餘額、銷售、交易、客戶、商品、優惠券與發票，並在確認後建立發票、付款連結與優惠券。

功能: 唯讀工具涵蓋帳戶資料、錢包餘額、銷售彙總、交易紀錄、單筆付款狀態、銀行結算，以及可搜尋的客戶、商品、優惠券與發票清單。建立類工具可新增客戶、商品、優惠券、付款連結或發票，並可請 PayPing 以簡訊或電子郵件寄送發票。清單每次最多回傳 50 筆並附總數；金額以托曼計，日期為 UTC。沒有任何工具可以提領、退款、撤銷付款或刪除資料。
適用情境: 適合讓助理回答 PayPing 商戶帳戶的查詢，或在對話中準備發票與付款連結。適合需要唯讀報表或先確認再建立流程的商戶。不適用於資金轉出、退款或原始付款 API 呼叫。
執行需求: 需要本機 Python 執行環境與 uv 或 uvx（PyPI 套件 payping-mcp），以及 Claude Code、Claude Desktop、Cursor 或 VS Code 等 MCP 用戶端。需要資料完整的 PayPing 商戶帳戶與已核准的 API 權杖，權杖透過環境變數 PAYPING_TOKEN 傳入。可用 PAYPING_MCP_PROXY 設定選用 HTTP 代理。需要能連線至 PayPing 的網路。

安裝前請注意

PAYPING_TOKEN 在其權限範圍內等同帳戶憑證，持有者即可操作帳戶，因此不要提交到版本庫，並只授予必要的權限與有效期限。建立與寄送類工具會寫入資料並標註 destructiveHint，用戶端應先要求確認。客戶名稱與備註來自他人，可能含有提示注入。餘額與銷售彙總使用面板端點，API 權杖可能被拒絕。

安裝

在 SourceWeft 中

開啟儀表板中的 PayPing，將其新增到工作區。
為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照儲存庫中的啟動說明。

README

[payping-mcp: let your AI agent check sales and send invoices on PayPing]

💳 payping-mcp

Your PayPing merchant account, for AI agents.
Let Claude, Cursor or Copilot read your balance, sales, transactions, customers, products, coupons and invoices,
and create invoices, payment links and coupons after you confirm, all from your own machine.

[PyPI] [Python] [CI] [MCP Registry] [License: MIT]

[Install in Cursor] [Install in VS Code]

Quick start · Token · Tools · Security · Troubleshooting · فارسی

What it can do

💰 Money: wallet balance, sales totals for a period, transactions, one payment's real status, settlements to your bank
🗂️ Shop data: list and search customers, products, coupons and invoices
🧾 Get paid: create a customer and an invoice with a pay page link, or a reusable payment link for a product, then have PayPing send the invoice by SMS/email
🔒 Safe by design: runs on your machine, talks only to PayPing, asks before creating anything, and cannot withdraw, refund, reverse a payment or delete anything

Quick start

You need:

a PayPing merchant account with a complete profile (PayPing only approves tokens for complete profiles)
uv
an MCP client: Claude Code, Claude Desktop, Cursor, VS Code, or any other

Then:

Create a PayPing token and wait for PayPing to approve it.
Add the server to your MCP client.
Check that it works.

1. Create a PayPing token

Sign in at app.payping.ir.
Open اتصالات (Connections) → توسعه دهندگان (Developers). The page title is توکن ها (Tokens).

Click توکن جدید (New token) and fill in the form:

Field	What to enter
توکن تست (test token)	Leave off to work with your real account.
نام توکن (token name)	Any name, e.g. `payping-mcp on my laptop`
آی‌پی‌های مجاز (allowed IPs)	Optional. If you fill it in, list the public IP your computer reaches PayPing from. Calls from any other IP fail with error code 166.
تاریخ انقضا (expiry date)	When the token stops working. Shorter is safer.
دسترسی‌ها (scopes)	See the table below.
توضیحات (description)	e.g. `MCP server for AI agents`
رمز پیامکی (SMS code)	Click ارسال رمز (send code) and type the code PayPing sends to your phone.

Click توکن جدید to submit. Copy the token now: PayPing shows it only once.
Wait for approval. PayPing staff review every new token. After approval, wait about 10 more minutes; until then the token gets HTTP 401.

Scopes. The form preselects گزارش پرداخت‌ها and ساخت پرداخت. Remove ساخت پرداخت: this server never uses it. Then add what you need:

Panel label	Scope	Tools that need it
گزارش پرداخت‌ها	`pay:read`	transactions, payment detail, withdrawals
مشاهده و گزارش از مشتریان	`customer:read`	list and get customers
ساخت و ویرایش مشتریان	`customer:write`	create customer
مشاهده و گزارش از محصولات	`product:read`	list and get products
ساخت و ویرایش محصولات	`product:write`	create product, create payment link
مشاهده و گزارش کدهای تخفیف	`coupon:read`	list and get coupons
ساخت و ویرایش کدهای تخفیف	`coupon:write`	create coupon
مشاهده و گزارش از فاکتورها	`invoice:read`	list and get invoices
ساخت و ویرایش فاکتور	`invoice:write`	create and send invoices
ساخت پرداخت	`pay:write`	none: leave it out

Want a read-only agent? Select only the read scopes. The create tools then fail with HTTP 403 and nothing in the account can change.

2. Add the server to your MCP client

Put your token where it says your-token.

Claude Code

This saves the server, with the token, in your user config (~/.claude.json), not in the project. Add --scope user to use it in every project.

Claude Desktop

Settings → Developer → Edit Config, then add:

json

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

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

Restart Claude Desktop after saving.

Cursor

Click Install in Cursor at the top and fill in the token, or add the Claude Desktop block to ~/.cursor/mcp.json.

VS Code (Copilot agent mode)

Add to .vscode/mcp.json. VS Code asks for the token once and stores it securely, so the file is safe to commit:

json

{  "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}" }    }  }}

{  "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}" }    }  }}

From GitHub instead of PyPI

Replace uvx payping-mcp with:

In JSON configs: "args": ["--from", "git+https://github.com/sepehr071/payping-mcp", "payping-mcp"].

Anything else

It's a standard stdio MCP server: run uvx payping-mcp, or pip install payping-mcp and run payping-mcp, with PAYPING_TOKEN in the environment.

3. Check that it works

Ask the agent: "Show my PayPing profile." You should see your PayPing username. If you see an error, look it up in Troubleshooting.

Then try:

"What is my PayPing balance and how much did I sell this month?"
"List this week's received payments and tell me which ones failed."
"Create an invoice for Ali Rezaei: 2 hours of consulting at 1,500,000 Toman each. Show me before you create it."
فاکتورهای پرداخت‌نشده این ماه را نشان بده.

Tools

All amounts are Toman, all dates UTC. Lists return at most 50 items per call and include total.

Read-only:

Tool	What it does
`payping_get_profile`	Account behind the token: username, name, contact, verification flags
`payping_get_balance`	Wallet balance
`payping_get_sales_summary`	Total sales, count and daily averages for a period (default last 30 days)
`payping_list_transactions`	Payments in a date range, received or paid
`payping_get_payment`	One payment by code, with its real status (paid and verified, cancelled, ...)
`payping_list_withdrawals`	Settlements to your bank account
`payping_get_withdrawal`	One settlement by code: IBAN, bank tracking number
`payping_list_customers`	Saved customers, searchable
`payping_get_customer`	One customer
`payping_list_products`	Products (financial items), searchable
`payping_get_product`	One product
`payping_list_coupons`	Discount coupons
`payping_get_coupon`	One coupon with buyer count and total
`payping_list_invoices`	Invoices, filter by status or customer
`payping_get_invoice`	One invoice with items and its pay page url

Create and send (the agent must confirm with you first):

Tool	What it does
`payping_create_customer`	Save a customer; returns its code
`payping_create_product`	Create a product with a fixed or payer-set price
`payping_create_payment_link`	Public pay page for a product: `https://ppng.ir/d/<product code>`
`payping_create_coupon`	Percent or Toman discount coupon
`payping_create_invoice`	Invoice for a saved customer; returns its pay page `https://ppng.ir/v/<invoice code>`
`payping_send_invoice`	PayPing sends the invoice to the customer by SMS/email

Privacy and security

Local only. The server runs on your machine and talks only to api.payping.ir and oauth.payping.ir. There is no relay server and no telemetry.
The token never leaks. It is sent only in the Authorization header to PayPing and never appears in tool output, errors or logs.
Treat the token like a password. Anyone who has it can use your account within its scopes. Don't commit it; use VS Code inputs or your client's user config. Give it only the scopes you need and an expiry date.
Lost or leaked token? In the panel, open the token and use حذف (delete) or تعویض توکن (swap token, which issues a new value). Then update your MCP config.
Confirm before creating. Create and send tools are annotated destructiveHint, so MCP clients ask before running them. Their descriptions also tell the agent to confirm the details with you.
No money moves out. No tool can withdraw, refund, reverse a payment or delete anything.
Prompt-injection aware. Customer names, descriptions and notes come from other people. The server tells the agent to treat them as data, never as instructions.

Good to know

Toman, not Rial. PayPing uses Toman in every service, and so does every tool.
Balance and sales summary are less certain. payping_get_balance and payping_get_sales_summary use endpoints from the PayPing dashboard, not the public API docs. If PayPing rejects them for API tokens, the tool error says so, and every other tool keeps working.
No raw payments. Raw POST /v3/pay payments are left out on purpose. They need your own callback server and a verify call within 10 minutes, or PayPing refunds the payer. Invoices and payment links use PayPing's own pay page instead.
Changing scopes needs a swap. After you edit a token's website, return URL or scopes, PayPing applies the change only after تعویض توکن (swap token). The swap gives a new token value; put it in your MCP config.

Troubleshooting

"PAYPING_TOKEN is not set"

The MCP client did not pass the token. Check the env block (or -e PAYPING_TOKEN=... for Claude Code) and restart the client.

"PayPing rejected the token (HTTP 401)"

One of these:

PayPing has not approved the token yet, or approved it less than 10 minutes ago.
The token expired. The panel shows منقضی شده (expired) on it.
The token was swapped or deleted, or was copied incompletely.

HTTP 403: "The token may lack the scope this tool needs"

Add the scope from the scope table to the token, then تعویض توکن (swap token) and use the new value.

"code 166"

Your IP is not in the token's allowed IPs. Add your current public IP to آی‌پی‌های مجاز or clear the list. If you route through a proxy, the IP PayPing sees is the proxy's exit IP.

"Could not reach PayPing" or "PayPing did not answer in time"

The server ignores system proxy settings on purpose. If your network needs a proxy to reach PayPing, set PAYPING_MCP_PROXY, e.g. http://127.0.0.1:10809. In testing, PayPing's API hosts answered both from Iran and from a foreign exit.

Claude Desktop says uvx is not found

Use the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.

How do I see exactly what the agent sees?

Errors that carry a PayPing trace id: give that id to PayPing support.

Configuration

فارسی

payping-mcp به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد موجودی، فروش، تراکنش‌ها، تسویه‌ها، مشتریان، محصولات، کدهای تخفیف و فاکتورهای حساب پی‌پینگ شما را ببیند، و پس از تأیید شما مشتری، محصول، لینک پرداخت، کد تخفیف و فاکتور بسازد.

روی سیستم خود شما اجرا می‌شود و توکن فقط به سرورهای پی‌پینگ فرستاده می‌شود.
برداشت، استرداد، برگشت پرداخت و حذف با این ابزار ممکن نیست.
مبالغ به تومان و تاریخ‌ها به وقت UTC هستند.

ساخت توکن:

در پنل پی‌پینگ به «اتصالات ← توسعه دهندگان» بروید و «توکن جدید» را بزنید.
نام توکن، تاریخ انقضا و توضیحات را وارد کنید. «آی‌پی‌های مجاز» اختیاری است؛ اگر پر کنید، درخواست از آی‌پی دیگر با خطای 166 رد می‌شود.
در «دسترسی‌ها» فقط موارد لازم را انتخاب کنید و «ساخت پرداخت» را حذف کنید؛ این ابزار به آن نیازی ندارد.
رمز پیامکی را بگیرید و وارد کنید. توکن فقط یک بار نمایش داده می‌شود؛ همان لحظه کپی کنید.
پروفایل شما باید کامل باشد. کارشناس پی‌پینگ توکن را تأیید می‌کند و تا حدود ۱۰ دقیقه بعد از تأیید ممکن است خطای 401 بگیرید.

نصب در Claude Code:

بعد بپرسید: «موجودی پی‌پینگ من چقدر است و این ماه چقدر فروختم؟»

توکن را مثل رمز عبور نگه دارید و در گیت قرار ندهید. اگر لو رفت، در پنل آن را حذف یا «تعویض توکن» کنید.

Development

bash

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

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

Tools live in src/payping_mcp/reports.py (account, money) and shop.py (customers, products, coupons, invoices); http.py is the only HTTP code. Each tool is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome.

Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions tests, publishes to PyPI and the MCP Registry, and creates the GitHub Release.

Disclaimer

Unofficial and not affiliated with or endorsed by PayPing. It uses PayPing's API with your own token. Follow PayPing's terms.

License

MIT

來源：README.md，提交 4ac0318

工具

工具後設資料尚未被收錄。

版本歷史

v0.1.0最新Oct 4, 2026

Variable	Required	Meaning
`PAYPING_TOKEN`	yes	API token from the PayPing panel
`PAYPING_MCP_PROXY`	no	HTTP proxy URL for every request, e.g. `http://user:pass@host:port`. System proxy settings are ignored.