PayPing README

💳 payping-mcp: PayPing MCP server for AI agents

Unofficial PayPing (پی‌پینگ) MCP server: your Iranian 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.

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

For AI agents

• What: MCP server 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 account. 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.
• 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; pass codes (customer, product, invoice) between tools.
• Machine-readable: server.json; catalog of all Iran MCP servers: awesome-iran-mcp (TOOLS.md, servers.json, llms.txt).

What PayPing MCP 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:

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:

   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.

4. Click توکن جدید to submit. Copy the token now: PayPing shows it only once.

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

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

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."
• فاکتورهای پرداخت‌نشده این ماه را نشان بده.

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.

Tools

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

Read-only (15):

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

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

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

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

Configuration

FAQ

Is there a PayPing API for AI agents or an MCP server? Yes. payping-mcp wraps the PayPing merchant API as MCP tools, so any MCP client can use it with your own token.

How do I use PayPing with Claude, Cursor or Copilot? 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.

Is it official, safe and free? 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.

Does it work outside Iran? 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.

فارسی: سرور MCP پی‌پینگ

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

• Bale MCP server for sending messages through a Bale bot, the other account tool in this family.
• More Iranian MCP servers (shopping, travel, books, health): awesome-iran-mcp.

Disclaimer

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

If this saves you clicks, a star helps others find it.

License

MIT