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:

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

Tools

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

Read-only:

Create and send (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

فارسی

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.

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