paziresh24-mcp

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

<div align="center">

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

# 🩺 paziresh24-mcp: Paziresh24 MCP server for AI agents

**Unofficial, read-only MCP server that lets your AI agent find the right Iranian doctor on Paziresh24 (پذیرش۲۴).**<br>
Search doctors by specialty, city, name and online visit, read profiles, prices, insurances and patient reviews,<br>
and see the free appointment times, all from Claude, Cursor or Copilot.

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

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

[Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)

</div>

---

## For AI agents

- **What:** Unofficial MCP server for Paziresh24 (پذیرش۲۴, paziresh24.com), the Iranian doctor appointment site. Queries in Persian or English; prices in Toman.
- **Install:** `claude mcp add paziresh24 -- uvx paziresh24-mcp` (stdio, needs [uv](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+).
- **Auth:** none. Optional `PAZIRESH24_MCP_PROXY` sets an HTTP proxy for every request.
- **Access:** read-only. It cannot log in, hold a slot, book, pay or post a review; give the user the doctor's profile `url` to book.
- **Tools:** 12, all prefixed `pz_`. Start with `pz_suggest` (words to city and specialty slugs), `pz_search_doctors`, `pz_doctor`, `pz_free_slots`, `pz_visit_price`.
- **Typical sequence:** `pz_suggest` -> `pz_search_doctors` -> `pz_doctor` -> `pz_first_available` or `pz_free_slots` -> `pz_visit_price`.
- **Use when:** the user wants to find a doctor, compare ratings, insurance and online visit fees, or see free appointment times in Iran.
- **Do not use when:** the user wants to actually book or pay, or needs medical advice.
- **Output:** compact JSON. Prices in Toman, dates Gregorian `YYYY-MM-DD`, times Tehran local `HH:MM`. Doctors are identified by their Persian slug; slot and price tools take `center_id`, `user_center_id` and `service_id` from `pz_doctor` (online visits use center `5532`).
- **Machine-readable:** [server.json](https://github.com/sepehr071/paziresh24-mcp/blob/main/server.json), and the catalog of all Iranian MCP servers [awesome-iran-mcp](https://github.com/sepehr071/awesome-iran-mcp) (`TOOLS.md`, `servers.json`, `llms.txt`).

## Why

Paziresh24 (paziresh24.com) lists tens of thousands of Iranian doctors, hospitals and clinics, with in-person
booking and online visits by phone or messenger. Picking one means comparing specialties, ratings, insurance,
prices and who has a free slot soon. An agent with `paziresh24-mcp` reads the same data the site shows and does
the comparing for you, then gives you the profile link to book:

> **You:** A female cardiologist in Tehran with an online visit today, not too expensive?
>
> **Agent:** *calls* `pz_search_doctors(city="tehran", specialty="cardiovascular", visit_type="online", gender="female", sort="earliest")` → `pz_doctor(slug="دکتر-هدیه-جباری-0")` → `pz_free_slots(center_id="5532", ...)` → `pz_visit_price(center_id="5532", ...)`
>
> Dr. Hedieh Jabbari (cardiologist, 5.0 from 11 ratings) has online visits over WhatsApp today from 15:00
> (10-minute slots: 15:00, 15:10, 15:20, ...). The visit is **500,000 Toman + 15,000 VAT = 515,000 Toman**.
> Book it here: https://www.paziresh24.com/dr/دکتر-هدیه-جباری-0/

<sub>Real tool output from 2026-10-06; slots and prices change all the time. Prices are in Toman.</sub>

## What it can do

- 🔎 **Search doctors** by city, specialty, name, online visit, gender, degree and work time, sorted by best, nearest free time or cheapest online visit
- 🏷️ **Resolve words**: Persian or English city and specialty names to search slugs, plus the site's type-ahead
- 👩‍⚕️ **Read a profile**: specialties, about text, medical council code, offices and hospitals with address, phone and map, services, weekly hours, insurance contracts, online visit channels
- 📅 **Find a time**: the earliest free appointment, the days with free slots, and the free times of each day (in person and online)
- 💳 **Know the cost**: online visit fee, VAT and the payable total in Toman
- ⭐ **Check reviews**: rating averages, average waiting time and paged patient reviews (no reviewer names)
- 🏥 **Hospitals and clinics**: departments, doctors, phone, website, map
- 🔒 **Read-only by design**: no login, no slot holds, no booking, no payment

## Quick start

You need [uv](https://docs.astral.sh/uv/getting-started/installation/).

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

```bash
claude mcp add paziresh24 -- uvx paziresh24-mcp
```
</details>

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

Settings → Developer → Edit Config, then add:

```json
{
  "mcpServers": {
    "paziresh24": { "command": "uvx", "args": ["paziresh24-mcp"] }
  }
}
```
</details>

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

Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`.
</details>

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

Click **Install in VS Code** above, or add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "paziresh24": { "type": "stdio", "command": "uvx", "args": ["paziresh24-mcp"] }
  }
}
```
</details>

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

It's a standard stdio MCP server: run `uvx paziresh24-mcp`, or `pip install paziresh24-mcp` and run `paziresh24-mcp`.
</details>

Then just ask:

- "A dermatologist in Shiraz who accepts Tamin Ejtemaei and has a free slot this week."
- "Cheapest online pediatrician visit available today?"
- "What do patients say about this doctor? https://www.paziresh24.com/dr/..."
- "Which cardiologists work at Treata hospital, and who is free soonest?"
- <span dir="rtl">چطور نوبت ویزیت آنلاین را لغو کنم و پولم برمی&zwnj;گردد؟</span>

## How it works

```text
  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  paziresh24-mcp  (runs on your machine)
      │
      │  HTTPS (JSON)
      ├──────▶  apigw.paziresh24.com      (search, free days and slots, prices, holidays)
      ├──────▶  drprofile.paziresh24.com  (doctor profiles)
      ├──────▶  ravi-apis.paziresh24.com  (reviews and ratings)
      ├──────▶  saman / biko.paziresh24.com (availability, insurance)
      └──────▶  www.paziresh24.com        (cities, specialties, hospitals, FAQ)
```

`paziresh24-mcp` runs locally and calls the same public endpoints the Paziresh24 website uses.
There's no hosted server in between, no API key, and nothing about you is sent anywhere else.

## Tools

Doctors are identified by their Persian slug, the part after `/dr/` in the profile URL
(`دکتر-هدیه-جباری-0`); slot and price tools take the `center_id`, `user_center_id` and `service_id`
that search results and `pz_doctor` return.

<details open>
<summary><b>🔎 Find</b> (4)</summary>

| Tool | What it does |
|---|---|
| `pz_suggest` | Persian or English words → city slugs, specialty slugs and query completions |
| `pz_search_doctors` | Doctors (or hospitals and clinics) by city, specialty, name, online visit, gender, degree, with sorting and paging |
| `pz_resolve_url` | A paziresh24.com link → doctor or center slug |
| `pz_center` | Hospital or clinic: address, phone, website, departments and doctors |
</details>

<details open>
<summary><b>👩‍⚕️ One doctor</b> (3)</summary>

| Tool | What it does |
|---|---|
| `pz_doctor` | Full profile: specialties, about, rating, insurances, online visit, centers, services, prices, weekly hours |
| `pz_first_available` | Earliest free in-person and online slot, per center |
| `pz_reviews` | Patient reviews (paged) with rating averages and waiting time per center |
</details>

<details open>
<summary><b>📅 Times and prices</b> (4)</summary>

| Tool | What it does |
|---|---|
| `pz_free_days` | Days with free slots over the whole booking window, days off and holidays |
| `pz_free_slots` | Free appointment times per day for a date range |
| `pz_visit_price` | Fee, VAT and payable total in Toman, and the refund-on-cancel setting |
| `pz_holidays` | Official Iranian holidays between two dates |
</details>

<details open>
<summary><b>ℹ️ Help</b> (1)</summary>

| Tool | What it does |
|---|---|
| `pz_faq` | Paziresh24's official FAQ: booking, cancelling, online visits, refunds |
</details>

All 12 tools are annotated `readOnlyHint: true` and return compact structured JSON, so they don't flood the agent's context.

## Good to know

- **Prices are in Toman** (1 Toman = 10 Rial). The APIs answer in Rial; the server divides by 10.
- **In-person office visits usually show price 0**: they are paid at the office and the fee is not published. Online visits have a real fee; `pz_visit_price` adds the VAT (3% in tests).
- **Times are