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.
PayPing merchant account for agents: balance, sales, invoices; create invoices and payment links.
Claude Code:claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcp
Auth:PAYPING_TOKEN (required, a PayPing API token whose scopes decide what works); PAYPING_MCP_PROXY (optional HTTP proxy).
Access: acts on the user's own account, so it is not read-only: 15 read tools and 6 create/send tools. Ask the user to confirm before any create or send tool. No tool can withdraw, refund, reverse or delete.
Tools: 21, prefixed 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.
Typical sequence:payping_create_customer -> payping_create_invoice -> payping_send_invoice; or payping_create_product -> payping_create_payment_link.
Units:Toman (not Rial), dates and times UTC.
Use when: the user wants to see or create invoices, payment links, coupons, customers or sales figures in their own PayPing account.
Do not use when: the task is taking raw payments, verifying or refunding a payment, or paying out; there are no tools for these.
Output: compact JSON; lists return at most 50 items with total (page with offset); pass codes (customer, product, invoice) between tools.
Machine-readable:server.json; catalog of all Iran MCP servers: iran-mcp (TOOLS.md, servers.json, llms.txt).
Why
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:callspayping_list_customers -> shows you the invoice details and waits for your OK -> payping_create_invoice -> payping_send_invoice
It 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.
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
Example prompts:
"Show my PayPing profile."
"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."
"Which invoices are overdue?"
"Create a product called Monthly plan at 490,000 Toman and give me a payment link."
"Create an invoice for Ali Rezaei: 2 hours of consulting at 1,500,000 Toman each. Show me before you create it."
فاکتورهای پرداختنشده این ماه را نشان بده.
موجودی پیپینگ من چقدر است و این ماه چقدر فروش داشتم؟
یک لینک پرداخت برای محصول «اشتراک ماهانه» بساز.
آخرین تسویههای من به حساب بانکی را نشان بده.
Quick start
You need:
a PayPing merchant account with a complete profile (PayPing only approves tokens for complete profiles)
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:
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
How it works
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.
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. Dates and times are UTC.
Not read-only. Six tools create data or message a real customer. Use read-only scopes if you want an agent that can only look.
Limits. Lists return at most 50 items per call (limit 1-50); page with offset. redirect_url must be https.
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.
What it does not do. No withdrawals, refunds, payment reversal, verification of raw payments, updates or deletes.
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.
Proxy. Set PAYPING_MCP_PROXY if your network needs a proxy to reach PayPing. System proxy variables are ignored on purpose.
Troubleshooting
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:
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.
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.
Use the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
Errors that carry a PayPing trace id: give that id to PayPing support.
FAQ
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.
Configuration
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.
فارسی: سرور MCP پیپینگ
payping-mcp یک سرور MCP غیررسمی برای پیپینگ (درگاه پرداخت و فاکتورنویسی آنلاین در ایران) است و به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد موجودی، فروش، تراکنشها، تسویهها، مشتریان، محصولات، کدهای تخفیف و فاکتورهای حساب پیپینگ شما را ببیند، و پس از تأیید شما مشتری، محصول، لینک پرداخت، کد تخفیف و فاکتور بسازد.
روی سیستم خود شما اجرا میشود و توکن فقط به سرورهای پیپینگ فرستاده میشود.
فقطخواندنی نیست: ابزارهای ساخت و ارسال روی حساب واقعی شما کار میکنند و باید پیش از اجرا تأیید بدهید. اگر فقط دسترسیهای خواندن را به توکن بدهید، چیزی در حساب تغییر نمیکند.
برداشت، استرداد، برگشت پرداخت و حذف با این ابزار ممکن نیست.
مبالغ به تومان و تاریخها به وقت UTC هستند.
ساخت توکن:
در پنل پیپینگ به «اتصالات ← توسعه دهندگان» بروید و «توکن جدید» را بزنید.
نام توکن، تاریخ انقضا و توضیحات را وارد کنید. «آیپیهای مجاز» اختیاری است؛ اگر پر کنید، درخواست از آیپی دیگر با خطای 166 رد میشود.
در «دسترسیها» فقط موارد لازم را انتخاب کنید و «ساخت پرداخت» را حذف کنید؛ این ابزار به آن نیازی ندارد.
رمز پیامکی را بگیرید و وارد کنید. توکن فقط یک بار نمایش داده میشود؛ همان لحظه کپی کنید.
پروفایل شما باید کامل باشد. کارشناس پیپینگ توکن را تأیید میکند و تا حدود ۱۰ دقیقه بعد از تأیید ممکن است خطای 401 بگیرید.
نصب در Claude Code:
claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcp
نمونه پرسشها
«موجودی پیپینگ من چقدر است و این ماه چقدر فروختم؟»
«فاکتورهای پرداختنشده این ماه را نشان بده.»
«یک فاکتور برای علی رضایی بساز: ۲ ساعت مشاوره، ساعتی ۱٬۵۰۰٬۰۰۰ تومان. قبل از ساخت به من نشان بده.»
«برای محصول من لینک پرداخت بساز.»
«آخرین تسویهها به حساب بانکی من چه بودهاند؟»
توکن را مثل رمز عبور نگه دارید و در گیت قرار ندهید. اگر لو رفت، در پنل آن را حذف یا «تعویض توکن» کنید.
Development
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.
Related servers
iran-mcp: catalog of all Iranian-service MCP servers
bale-mcp for sending messages through a Bale bot, the other account tool in this family
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.
Author
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.