ponisha-mcp

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

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

نصب سریع (Claude Code)

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, 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:

⚠️ 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

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, …)

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

From source

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

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

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