# ponisha-mcp

**سرور MCP پونیشا**: دستیار هوش مصنوعی‌تان (Claude، Cursor و…) را به حساب [پونیشا](https://ponisha.ir) وصل کنید تا پروژه‌ها را بگردد، پیشنهاد ثبت کند، پیام کارفرماها را بخواند و جواب بدهد و پروفایل‌تان را به‌روز کند.

> ⚠️ **غیررسمی.** پونیشا API عمومی ندارد. این ابزار از همان APIهای داخلی‌ای استفاده می‌کند که سایت ponisha.ir خودش استفاده می‌کند، و هیچ ارتباطی با پونیشا ندارد. این APIها ممکن است هر وقت تغییر کنند، و خودکارسازی حساب ممکن است با قوانین پونیشا مغایر باشد. فقط روی حساب خودتان استفاده کنید و پیشنهادها و پیام‌ها را پیش از ارسال خودتان ببینید.

### نصب سریع (Claude Code)

```bash
npx -y github:Kia-Karami/ponisha-mcp login
claude mcp add ponisha -- npx -y github:Kia-Karami/ponisha-mcp
```

دستور اول شما را وارد حساب پونیشا می‌کند (رمز با `*` نمایش داده می‌شود و فقط روی کامپیوتر خودتان ذخیره می‌شود). دستور دوم ابزار را به Claude Code اضافه می‌کند. حالا می‌توانید بپرسید: «پروژه‌های باز طراحی لوگو با بودجه‌ی بیش از ۵ میلیون تومان را پیدا کن.»

### چه کارهایی می‌کند؟
- جستجوی پروژه‌ها با کلمه، مهارت و دسته‌بندی؛ دیدن جزئیات پروژه و هزینه‌ی پیشنهاد (اعتبار)
- ثبت و ویرایش پیشنهاد، همراه با مراحل پرداخت
- خواندن گفتگوها و پیام‌ها و ارسال پاسخ
- ویرایش پروفایل (عنوان شغلی، درباره‌ی من، مهارت‌ها)
- میز کار، اعلان‌ها، کیف پول و تنظیمات

**پروژه‌هایی که کارفرما فریلنسرش را انتخاب کرده** را تشخیص می‌دهد. پونیشا این پروژه‌ها را همچنان «باز» نشان می‌دهد، اما این ابزار آن‌ها را در جستجو پنهان می‌کند، در جزئیات پروژه هشدار می‌دهد و روی آن‌ها پیشنهاد ثبت نمی‌کند تا اعتبارتان هدر نرود.

همه‌ی مبالغ به **تومان** هستند، مثل خود سایت. ابزارهایی که چیزی را تغییر می‌دهند پیش از اجرا از شما تأیید می‌گیرند؛ با `PONISHA_READ_ONLY=1` کاملاً خاموش می‌شوند.

---

## English

An unofficial MCP server for [Ponisha](https://ponisha.ir), the Iranian freelancing platform. It lets an AI assistant search projects, submit bids, read and answer chats, and edit your profile.

Ponisha has no public API. This server calls the same private endpoints the ponisha.ir web app uses:

| Service | Base URL | Used for |
|---|---|---|
| api | `https://api.ponisha.ir/api/v1` | auth, projects, bids, users, profile, wallet, desks |
| search | `https://search.ponisha.ir/v1` | project / freelancer search (public) |
| chat | `https://chat.ponisha.ir/v1` | conversations and messages |

> ⚠️ Not affiliated with Ponisha. These are undocumented internal APIs. They can change at any time, and automating an account may break Ponisha's terms of service. Use it only on your own account, review bids and messages before they're sent, and don't spam.

### Install

Requires Node.js 18.17 or newer.

**Claude Code**

```bash
npx -y github:Kia-Karami/ponisha-mcp login
claude mcp add ponisha -- npx -y github:Kia-Karami/ponisha-mcp
```

**Claude Desktop / Cursor / other clients** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)

```json
{
  "mcpServers": {
    "ponisha": {
      "command": "npx",
      "args": ["-y", "github:Kia-Karami/ponisha-mcp"]
    }
  }
}
```

**From source**

```bash
git clone https://github.com/Kia-Karami/ponisha-mcp.git
cd ponisha-mcp && npm install
npm run login
claude mcp add ponisha -- node "$PWD/dist/index.js"
```

### Logging in

Pick one:

1. **Interactive (easiest)**: run `npx -y github:Kia-Karami/ponisha-mcp login` (or `npm run login` from source). Log in with your password, shown as `*`, or with an SMS code.
2. **Password from env**: set `PONISHA_USERNAME` (mobile or email) and `PONISHA_PASSWORD` in the server's config, then ask the assistant to call `ponisha_login_password`. Your credentials stay in the config and never appear in the chat.
3. **SMS code in chat**: the assistant calls `ponisha_login_otp_request` with your mobile number, you tell it the code, and it calls `ponisha_login_otp_verify`.
4. **Existing token**: copy the `Authorization: Bearer …` header from any `api.ponisha.ir` request in your browser's DevTools and set it as `PONISHA_TOKEN`.

The session is saved only on your computer, in `~/.ponisha-mcp/session.json` (file mode 600). `ponisha_logout` deletes it. Never share that file.

### Tools

**Read (no login needed)**
- `ponisha_search_projects`: text, skills, categories, open-only, sorting, paging
- `ponisha_get_project`, `ponisha_list_project_bids`
- `ponisha_list_skills`, `ponisha_list_categories`
- `ponisha_search_freelancers`, `ponisha_get_profile`, `ponisha_get_user_reviews`, `ponisha_list_portfolio`

**Read (login needed)**
- `ponisha_get_me`, `ponisha_my_bids`, `ponisha_get_bid`
- `ponisha_my_dashboard`: workroom projects/bids/summary, my projects, desks, notifications, wallet, settings, resume (some sections take 10–20 s)
- `ponisha_get_desk`: the workspace after a bid is accepted (payments, requests, files)
- `ponisha_list_conversations`, `ponisha_get_messages`, `ponisha_get_conversation_info`
- `ponisha_api_get`: GET any endpoint

**Write (acts on your real account)**
- `ponisha_submit_bid`, `ponisha_update_bid` (Ponisha has no way to withdraw a bid)
- `ponisha_send_message`
- `ponisha_update_profile`, `ponisha_update_skills`
- `ponisha_api_request`: any method on any endpoint

Write tools are marked with MCP annotations, so clients ask you before running them. Set `PONISHA_READ_ONLY=1` to turn them all off.

### Notes
- **Money is in Toman**, the same numbers ponisha.ir shows. A 5 million Toman bid is `amount: 5000000`. Bids must be between 100,000 and 1,000,000,000 Toman, with delivery in 1–180 days.
- **Projects that already hired someone.** Ponisha keeps a project marked open (باز) after the employer has chosen a freelancer («کارفرما این پیشنهاد را انتخاب کرده است»). The server spots this from the project's bid list (a bid with status «تایید شده»): search hides those projects by default (`hide_taken: false` shows them, marked `already_hired: true`), `ponisha_get_project` adds a CLOSED warning, and `ponisha_submit_bid` refuses to bid on them, or when it can't check, so you don't waste credits.
- **Milestones**: if you pass `payments`, they must add up exactly to `amount`. If you leave it out, one milestone for the full amount is sent.
- **Bids cost credits, and the price depends on the project.** `ponisha_get_project` shows it as `coin_needed`: it goes up with the budget (about 1 credit under 500K Toman, 2 credits for 500K–2M, 5 credits for 6M and up). A promoted bid costs about 10× (`promoted_coin_needed`). The free plan gives 5 credits a month; Gold gives 500. With too few left, Ponisha rejects the bid.
- Sharing contact info in bids or chat is against Ponisha's rules and is filtered.

### Environment variables

| Var | Purpose |
|---|---|
| `PONISHA_USERNAME` / `PONISHA_PASSWORD` | credentials for `ponisha_login_password` |
| `PONISHA_TOKEN` | use this bearer token instead of the stored session |
| `PONISHA_READ_ONLY` | `1` turns off all write tools |
| `PONISHA_SESSION_DIR` | where the session is stored (default `~/.ponisha-mcp`) |
| `PONISHA_MAX_RESPONSE_CHARS` | maximum response size per tool call (default 60000) |

### Example prompts
- "Find open Python/Django projects on Ponisha posted this week with a budget over 20M Toman, and summarize the best 5 for me."
- "Draft a bid for project 762972: 8M Toman, 10 days. Show it to me before you submit."
- "Check my Ponisha messages and draft replies to anything unread."
- "Update my Ponisha headline to 'Full-stack Python & React developer'."

### Development

```bash
npm install     # also builds
npm test        # builds, then runs the unit tests
```

- `src/index.ts`: entry point (`ponisha-mcp` starts the stdio server, `ponisha-mcp login` logs in)
- `src/server.ts`: `createServer()` registers the tools; importing it has no side effects
- `src/client.ts`: HTTP client with a 20-second timeout per request, plus session storage
- `src/lib.ts`: pure helpers (request bodies, formatting, errors), tested in `test/`

Errors are always returned as `isError` results, never thrown. Nothing but the MCP protocol is written to stdout.

### Status

Tested against the live site in November 2026, from an Iranian IP: search and all read tools, profile and skills editing, and submitting a bid. It hasn't been tried from outside Iran. Sending a chat message and editing a bid are built to the site's request format but haven't been used for real yet.

### License

MIT