payping-mcp
Advanced tools
Local MCP server for PayPing (payping.ir) merchants: let AI agents read balance, sales, transactions, withdrawals, customers, products, coupons and invoices, and create customers, products, payment links, coupons and invoices.
Let your AI agent work with your PayPing (پی‌پینگ) merchant account.
An unofficial MCP server for PayPing, the Iranian payment gateway and invoicing service:
read balance, sales, transactions, customers, products, coupons and invoices, and create invoices, payment links and coupons after you confirm, from Claude, Cursor or Copilot.
For AI agents · Why · What it can do · Quick start · Tools · Security · Troubleshooting · FAQ · فارسی
uvx payping-mcp (needs uv, Python 3.10+; or pip install payping-mcp). Transport: stdio.claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcpPAYPING_TOKEN (required, a PayPing API token whose scopes decide what works); PAYPING_MCP_PROXY (optional HTTP proxy).payping_*. Start with payping_get_profile, payping_get_balance, payping_get_sales_summary, payping_list_transactions, payping_list_invoices. Balance and sales summary use dashboard endpoints that PayPing may reject for API tokens; the other tools still work.payping_create_customer -> payping_create_invoice -> payping_send_invoice; or payping_create_product -> payping_create_payment_link.total (page with offset); pass codes (customer, product, invoice) between tools.server.json; catalog of all Iran MCP servers: iran-mcp (TOOLS.md, servers.json, llms.txt).The PayPing panel is built for people clicking through screens. Answering "how much did I sell this month, which payments failed, and who still owes me?" means opening several pages, and creating an invoice means filling in a customer, items and a send step by hand. With payping-mcp an agent does it in a few calls: it reads the numbers, drafts the invoice, shows you the details and only creates and sends it after you say yes.
You: Create an invoice for Ali Rezaei: 2 hours of consulting at 1,500,000 Toman each, and send it.
Agent: calls
payping_list_customers-> shows you the invoice details and waits for your OK ->payping_create_invoice->payping_send_invoiceIt gives you the public pay page link (
https://ppng.ir/v/<invoice code>) and tells you PayPing sent the invoice by SMS/email.
Everything runs on your machine with your own token. There is no hosted relay in between.
Example prompts:
You need:
Then:
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.
Put your token where it says your-token.
claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcp
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.
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"payping": {
"command": "uvx",
"args": ["payping-mcp"],
"env": { "PAYPING_TOKEN": "your-token" }
}
}
}
Restart Claude Desktop after saving.
Click Install in Cursor at the top and fill in the token, or add the Claude Desktop block to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Click Install in VS Code at the top, or add to .vscode/mcp.json. VS Code asks for the token once and stores it securely, so the file is safe to commit:
{
"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
Or in ~/.codex/config.toml:
[mcp_servers.payping]
command = "uvx"
args = ["payping-mcp"]
[mcp_servers.payping.env]
PAYPING_TOKEN = "your-token"
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"payping": {
"command": "uvx",
"args": ["payping-mcp"],
"env": { "PAYPING_TOKEN": "your-token" }
}
}
}
Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.
Replace uvx payping-mcp with:
uvx --from git+https://github.com/sepehr071/payping-mcp payping-mcp
In JSON configs: "args": ["--from", "git+https://github.com/sepehr071/payping-mcp", "payping-mcp"].
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.
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 the example prompts under What it can do.
All amounts are Toman, all dates UTC. Lists return at most 50 items per call and include total.
Read-only (15):
| 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 (6; 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 |
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 runs locally and calls PayPing's API with your own token. There's no hosted server in between. It ignores system proxy settings, retries a failed GET once after a second on HTTP 429, 502 or 503 (never a create or send call), keeps no cache, and returns each result as one compact JSON block with empty fields dropped.
api.payping.ir and oauth.payping.ir. There is no relay server and no telemetry.Authorization header to PayPing and never appears in tool output, errors or logs.inputs or your client's user config. Give it only the scopes you need and an expiry date.destructiveHint, so MCP clients ask before running them. Their descriptions also tell the agent to confirm the details with you.offset. redirect_url must be https.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.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.PAYPING_MCP_PROXY if your network needs a proxy to reach PayPing. System proxy variables are ignored on purpose.The MCP client did not pass the token. Check the env block (or -e PAYPING_TOKEN=... for Claude Code) and restart the client.
One of these:
Add the scope from the scope table to the token, then تعویض توکن (swap token) and use the new value.
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.
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.
uvx is not foundUse the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
npx @modelcontextprotocol/inspector -e PAYPING_TOKEN=your-token uvx payping-mcp
Errors that carry a PayPing trace id: give that id to PayPing support.
Yes. payping-mcp wraps the PayPing merchant API as 21 MCP tools, so any MCP client can use it with your own token.
Create a PayPing token, then add the server with claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcp or the config blocks in Quick start.
It is unofficial and free (MIT). It runs on your machine, talks only to PayPing and cannot withdraw or refund. Give the token only the scopes you need; read-only scopes make it read-only.
The tools are annotated so MCP clients ask before running them, and the server tells the agent to confirm the details with you first. Your client's permission settings have the last word, and a token with only read scopes cannot create anything.
No. There are no tools to withdraw, refund, reverse a payment or delete anything.
PayPing staff review every new token, and the token starts working about 10 minutes after approval.
They use dashboard endpoints, not the documented public API, and PayPing may reject them for API tokens. The error says so and the other tools keep working.
The PayPing API hosts answered both from Iran and from a foreign exit in testing. You still need a PayPing merchant account; set PAYPING_MCP_PROXY if your network needs a proxy.
Toman, in every tool.
| Variable | Required | Meaning |
|---|---|---|
PAYPING_TOKEN | yes | API token from the PayPing panel (app.payping.ir, Connections > Developers > Tokens). Secret. |
PAYPING_MCP_PROXY | no | HTTP proxy URL for every request, e.g. http://user:pass@host:port. System proxy settings are ignored. |
payping-mcp یک سرور MCP غیررسمی برای پی‌پینگ (درگاه پرداخت و فاکتورنویسی آنلاین در ایران) است و به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد موجودی، فروش، تراکنش‌ها، تسویه‌ها، مشتریان، محصولات، کدهای تخفیف و فاکتورهای حساب پی‌پینگ شما را ببیند، و پس از تأیید شما مشتری، محصول، لینک پرداخت، کد تخفیف و فاکتور بسازد.
ساخت توکن:
نصب در Claude Code:
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
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.
Unofficial and not affiliated with or endorsed by PayPing. It uses PayPing's API with your own token. Follow PayPing's terms. It acts on your own account: review what the agent is about to create or send.
If this saves you clicks, a star helps others find it.
Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp. If this saves you time, a star on the repo helps other people find it.
FAQs
Local MCP server for PayPing (payping.ir) merchants: let AI agents read balance, sales, transactions, withdrawals, customers, products, coupons and invoices, and create customers, products, payment links, coupons and invoices.
We found that payping-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
Cloudflare introduces tsrs, a Rust port of TypeScript’s compiler promising faster checks and lower memory use, with the TypeScript team’s help.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.