payping-mcp

<!-- mcp-name: io.github.sepehr071/payping-mcp -->

<div align="center">

<img src="https://raw.githubusercontent.com/sepehr071/payping-mcp/main/.github/banner.png" alt="payping-mcp: unofficial PayPing MCP server for Claude, Cursor and Copilot" width="100%">

# 💳 payping-mcp: PayPing MCP server for AI agents

**Unofficial PayPing (<span dir="rtl">پی&zwnj;پینگ</span>) MCP server: your Iranian merchant account, for AI agents.**<br>
Let Claude, Cursor or Copilot read your balance, sales, transactions, customers, products, coupons and invoices,<br>
and create invoices, payment links and coupons after you confirm, all from your own machine.

[![PyPI](https://img.shields.io/pypi/v/payping-mcp?color=2563eb)](https://pypi.org/project/payping-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/payping-mcp)](https://pypi.org/project/payping-mcp/)
[![CI](https://github.com/sepehr071/payping-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/payping-mcp/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fpayping--mcp-7c3aed)](https://registry.modelcontextprotocol.io/?q=payping-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/payping-mcp/blob/main/LICENSE)

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=payping&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJwYXlwaW5nLW1jcCJdLCJlbnYiOnsiUEFZUElOR19UT0tFTiI6InlvdXItdG9rZW4ifX0=)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_payping--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=payping&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22payping-mcp%22%5D%2C%22env%22%3A%7B%22PAYPING_TOKEN%22%3A%22your-token%22%7D%7D)

[Quick start](#quick-start) · [Token](#1-create-a-payping-token) · [Tools](#tools) · [Security](#privacy-and-security) · [Troubleshooting](#troubleshooting) · [FAQ](#faq) · [فارسی](#فارسی)

</div>

---

## 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](https://docs.astral.sh/uv/getting-started/installation/), 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](server.json); catalog of all Iran MCP servers: [awesome-iran-mcp](https://github.com/sepehr071/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](https://docs.astral.sh/uv/getting-started/installation/)
- an MCP client: Claude Code, Claude Desktop, Cursor, VS Code, or any other

Then:

1. [Create a PayPing token](#1-create-a-payping-token) and wait for PayPing to approve it.
2. [Add the server](#2-add-the-server-to-your-mcp-client) to your MCP client.
3. [Check that it works](#3-check-that-it-works).

### 1. Create a PayPing token

1. Sign in at [app.payping.ir](https://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` |
   | آی&zwnj;پی&zwnj;های مجاز (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. |
   | دسترسی&zwnj;ها (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 **گزارش پرداخت&zwnj;ها** and **ساخت پرداخت**. Remove **ساخت پرداخت**: this server never uses it. Then add what you need:

| Panel label | Scope | Tools that need it |
|---|---|---|
| گزارش پرداخت&zwnj;ها | `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.

### 2. Add the server to your MCP client

Put your token where it says `your-token`.

<details open>
<summary><b>Claude Code</b></summary>

```bash
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.
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings → Developer → Edit Config, then add:

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

Restart Claude Desktop after saving.
</details>

<details>
<summary><b>Cursor</b></summary>

Click **Install in Cursor** at the top and fill in the token, or add the Claude Desktop block to `~/.cursor/mcp.json`.
</details>

<details>
<summary><b>VS Code (Copilot agent mode)</b></summary>

Add to `.vscode/mcp.json`. VS Code asks for the token once and stores it securely, so the file is safe to commit:

```json
{
  "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>

<details>
<summary><b>From GitHub instead of PyPI</b></summary>

Replace `uvx payping-mcp` with:

```bash
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"]`.
</details>

<details>
<summary><b>Anything else</b></summary>

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.
</details>

### 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](#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."
- <span dir="rtl">فاکتورهای پرداخت&zwnj;نشده این ماه را نشان بده.</span>

## How it works

```text
  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