PayPing

payping-mcp: PayPing MCP server for AI agents

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 · فارسی

For AI agents

• What: unofficial MCP server (model context protocol) for a PayPing (payping.ir, Iran) merchant account. Amounts are Toman, dates UTC.
• Install: uvx payping-mcp (needs uv, Python 3.10+; or pip install payping-mcp). Transport: stdio.
• 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: *calls* payping_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/ ) 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)
• uv
• an MCP client: Claude Code, Claude Desktop, Cursor, VS Code, or any other

Then:

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

1. Create a PayPing token

1. Sign in at app.payping.ir.
2. Open اتصالات (Connections) → توسعه دهندگان (Developers). The page title is توکن ها (Tokens).
3. Click توکن جدید (New token) and fill in the form:

1. Click توکن جدید to submit. Copy the token now: PayPing shows it only once.
2. 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:

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

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.

Claude Desktop

Settings → Developer → Edit Config, then add:

{

"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 (or .cursor/mcp.json in a project).

VS Code (Copilot agent mode)

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

</details>

Codex CLI

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"

</details>

Gemini CLI

Add to ~/.gemini/settings.json:

{

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

</details>

Windsurf

Add the Claude Desktop block to ~/.codeium/windsurf/mcp_config.json.

From GitHub instead of PyPI

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"].

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 the example prompts under [What it can d