Skip to main content
Glama

iran-doctor-mcp

Find a doctor by name across Iran's online booking sites: first free appointment, visit price and a booking link, in one answer.

An MCP server (for Claude and other MCP clients) plus a command-line tool. It searches five booking platforms in parallel, merges the profiles that belong to the same person, and produces:

  • a Persian report for the chat (summary → one block per doctor → best options → next steps), and

  • an interactive HTML page with filters, sorting and booking buttons that you can open in any browser.

فارسی: نام پزشک (و در صورت امکان شهر) را بدهید؛ این ابزار در پذیرش۲۴، دکترتو، نوبت دات آی آر، دکترنکست و درمانکده جستجو می‌کند و برای هر پزشک زودترین نوبت خالی، هزینه ویزیت، تلفن مطب و لینک رزرو را نشان می‌دهد. پروفایل‌های یک پزشک در سایت‌های مختلف یکی می‌شوند و نتیجه یک صفحه HTML تعاملی هم دارد.

Version

1.1.0 (CHANGELOG)

Runtime

Node.js ≥ 22, two dependencies (@modelcontextprotocol/sdk, zod)

Transport

MCP over stdio

Tools

search_doctor, get_doctor_details, list_platforms

Tests

npm test (offline, ~1 s) · npm run test:live (real sites)


Contents


Related MCP server: Doctolib MCP

Quick start

npm install
npm test                                   # offline unit tests
npm run report -- "مریم احمدی" تهران        # search and open the HTML report in your browser
npm start                                  # run the MCP server on stdio (normally your MCP client starts it)

Connect to an MCP client

Claude Code

This folder already contains .mcp.json, so Claude Code picks the server up when started here. To use it in every project:

claude mcp add iran-doctor -s user -- node /absolute/path/to/iran-doctor-mcp/src/index.js

After changing the code, reconnect with /mcp.

Claude Desktop and other clients

Add the server to the client's MCP configuration (for Claude Desktop: claude_desktop_config.json):

{
  "mcpServers": {
    "iran-doctor": {
      "command": "node",
      "args": ["/absolute/path/to/iran-doctor-mcp/src/index.js"],
      "env": {
        "DOCTOR_MCP_REPORT_DIR": "/absolute/path/for/reports"
      }
    }
  }
}

If the package is installed globally (npm install -g .), "command": "iran-doctor-mcp" with no args also works.

Try it with the MCP Inspector

npm run inspect

Then just ask, e.g. «برای دکتر مریم احمدی در تهران زودترین نوبت را پیدا کن».


Tools

search_doctor

Searches all (or selected) platforms in parallel and returns the Persian report. Unless disabled, it also saves the HTML page and returns it as a second content item (resource_link, file://…), with the path also written at the top of the report.

Argument

Type

Default

Description

name

string, 2–100 chars

— (required)

Doctor's name in Persian. Last name alone works. Titles («دکتر») and Arabic letters (ي/ك) are normalised.

city

string, ≤ 50 chars

—

Persian city name. Each platform is searched inside that city, so local doctors are not crowded out.

platforms

array

all

Subset of paziresh24, doctoreto, nobat, drnext, darmankade.

max_per_platform

1–10

5

How many matching doctors to open per platform.

visit_type

all | in_person | online

all

Filter visit types in the report.

sort

soonest | cheapest | rating

soonest

Order of doctors and options.

include_json

boolean

false

Append the raw structured results as JSON.

html

boolean

DOCTOR_MCP_HTML (on)

Save the interactive HTML page.

isError is set only when every platform failed. A single failing site is reported in the status line and the other results are still returned.

get_doctor_details

Every visit type with price, first free time, clinic address and phones for one profile (nobat.ir also lists the next open days).

Argument

Description

platform

One of the platform ids.

id

The id from search_doctor JSON, or that platform's profile URL: paziresh24 = slug (دکتر-مریم-احمدی-5), doctoreto = slug/code (dr-mehran-ahmadi/GxbEdZ), nobat = page slug (35865), drnext = id (zvOqzwrOZ4BZ), darmankade = numeric id (423925).

list_platforms

Supported platforms, what each provides, and the sites that were checked but excluded (and why). It needs no network access.


The report

search_doctor returns Markdown in Persian, written for the patient:

  1. Summary: how many different doctors share the name (by field), how many have a free slot now, and the soonest in-person and online slot.

  2. One block per doctor: rating, sites, insurance, and a table of options (site · visit type/clinic · first free time · price · booking link), followed by clinic phones. Options without a free slot come last. Doctors with no free slot at all are listed briefly at the end, with profile links and phones.

  3. Best options: soonest/cheapest in-person and online. When one option wins both, it is shown once («زودترین و ارزان‌ترین نوبت حضوری»).

  4. Next steps: pick the right doctor, where to book, the online fallback, try another site, phone the clinic, insurance and cancellation, emergency 115.

  5. Sites checked: one line. Failures are listed there and also flagged at the top.

Dates use the Jalali calendar with Persian digits and a relative hint (امروز · فردا · ۳ روز دیگر · حدود ۲ هفته دیگر). Phone numbers and URLs keep Latin digits so they can be dialed and clicked. Prices are in Toman. Rial prices from Paziresh24 and DrNext are converted.

# نتیجه جستجوی پزشک: «مریم احمدی» در تهران
_زمان جستجو: چهارشنبه ۲۷ آبان، ساعت ۱۱:۰۶ به وقت تهران · ۵ از ۵ سایت نوبت‌دهی بررسی شد_

📄 **نسخه تعاملی (HTML) این گزارش:** `/…/reports/doctor-20261118-110600-مریم-احمدی-تهران.html`

## خلاصه
- با این نام **۷ پزشک مختلف** پیدا شد (کاردرمانی، زنان و زایمان، قلب و عروق، …).
- **۲** پزشک الان نوبت خالی اینترنتی دارند و **۵** پزشک ندارند.
- **زودترین نوبت حضوری:** چهارشنبه ۲۷ آبان، ساعت ۰۸:۱۰ (امروز) — دکتر مریم احمدی در پذیرش۲۴

## ۱) پزشکان و نوبت‌های خالی (مرتب‌سازی: زودترین نوبت)

### ۱. دکتر مریم احمدی — کارشناس ارشد کاردرمانی · تهران
- امتیاز: ⭐ ۵٫۰ از ۵ (۱۱ نظر، رضایت ۱۰۰٪) در پذیرش۲۴
- در ۲ سایت: پذیرش۲۴، دکترتو

| سایت | نوع ویزیت / محل | اولین نوبت خالی | هزینه | لینک |
|---|---|---|---|---|
| پذیرش۲۴ | حضوری — مطب مریم احمدی، قیطریه | **چهارشنبه ۲۷ آبان، ساعت ۰۸:۱۰ (امروز)** | ۵۰٬۰۰۰ تومان (هنگام رزرو) | [رزرو](…) |
| دکترتو | مشاوره تلفنی | **چهارشنبه ۲۷ آبان، ساعت ۱۴:۰۰ (امروز)** | ۱۰۰٬۰۰۰ تومان | [رزرو](…) |

How "same doctor" is decided

Profiles are merged only when name, city and medical field all match:

  • Names are normalised: titles (دکتر, پروفسور), «سید/سیده», Arabic letters, ZWNJ and spacing are ignored.

  • Fields are canonicalised, so «کارشناسی ارشد کار درمانی» = «کارشناس ارشد کاردرمانی» and «فوق تخصص زنان و زایمان» = «متخصص زنان و زایمان». A cardiologist and a midwife with the same name stay separate.

  • Missing city or specialty: a profile without one joins a group only if exactly one group matches.

This is a heuristic. Two different doctors with the same name, city and field would be merged. The report reminds the patient to check the medical council number (شماره نظام پزشکی) before booking.


HTML report and CLI

Every search writes one self-contained file, doctor-<YYYYMMDD-HHMMSS>-<name>-<city>.html, in DOCTOR_MCP_REPORT_DIR (default: the OS temp folder, see Configuration). Its data is embedded in the file, so there is no server or build step. It works offline, except for the web font, which falls back to Tahoma.

What's on the page

  • Summary tiles: doctors found, how many have a free slot, and the soonest in-person and online slot. Clicking a tile jumps to that doctor.

  • Filters:

    • text search across name, specialty, clinic and address

    • visit type (all / in-person / online)

    • "only free slots"

    • specialty chips and site chips (with counts)

    • sorting by soonest, cheapest or rating

  • Best-option cards: these follow the active filters.

  • Doctor cards: «رزرو نوبت» (book) buttons, relative-time pills, tap-to-call phones and profile links. Options without a free slot are folded away.

  • Opening it later: relative times are computed when the page is opened. A banner warns when the data is more than 3 hours old.

  • Display: light/dark mode (it follows the system and can be toggled), mobile layout, and print / save as PDF (folded options are expanded for printing).

CLI

npm run report -- "<doctor name>" [city] [options]
# or, after `npm install -g .`
iran-doctor-report "<doctor name>" [city] [options]

Option

Description

--max <n>

Doctors to open per site (1–10, default 5).

--platforms a,b

Subset of platform ids.

--sort <s>

soonest | cheapest | rating (Markdown output).

--md

Also print the Persian Markdown report.

--json

Print the raw results as JSON (no HTML unless --html).

--html

Save HTML even with --json.

--no-open

Save the page but don't open the browser.

Exit codes: 0 success · 1 every site failed · 2 bad arguments · 78 invalid configuration.

iran-doctor-report احمدی شیراز --platforms paziresh24,doctoreto --no-open
iran-doctor-report "مریم احمدی" تهران --json > result.json

Configuration

All settings are optional environment variables. They are validated at startup. An invalid value stops the process with a one-line message and exit code 78.

Variable

Default

Description

DOCTOR_MCP_TIMEOUT_MS

20000

Timeout of one HTTP request (1000–120000).

DOCTOR_MCP_RETRIES

2

Retries per request on network errors, timeouts, 429 and 5xx (0–5). Other 4xx responses are never retried.

DOCTOR_MCP_PLATFORM_DEADLINE_MS

45000

Hard deadline for one platform's whole search. A slower site is reported as failed.

DOCTOR_MCP_MAX_RESPONSE_BYTES

8388608

Max response body size (8 MB).

DOCTOR_MCP_CACHE_TTL

120

Seconds to cache identical searches (per platform). 0 disables the cache.

DOCTOR_MCP_HTML

true

Save an HTML page for every search_doctor call. The tool argument html overrides this.

DOCTOR_MCP_REPORT_DIR

<OS temp>/iran-doctor-mcp/reports/

Where HTML reports are written. The default is always writable, also for global / npx installs; set this to keep reports somewhere permanent.

DOCTOR_MCP_REPORT_KEEP

200

Keep at most this many reports; the oldest are deleted. 0 keeps all.

DOCTOR_MCP_LOG_LEVEL

info (CLI: warn)

debug | info | warn | error | silent.

Logging. Logs are JSON lines on stderr (stdout is reserved for the MCP protocol), for example:

{"t":"2026-11-18T09:13:23.449Z","level":"info","msg":"search done","ms":9696,"doctors":10,"failed":[]}

Use DOCTOR_MCP_LOG_LEVEL=debug to see every HTTP request with its timing, size, attempt number and errors.


How it works

flowchart LR
  C[MCP client / CLI] -->|search_doctor| S[server.js]
  S --> R[search.js<br/>parallel · deadline · cache]
  R --> P1[paziresh24<br/>JSON API]
  R --> P2[doctoreto<br/>__NEXT_DATA__]
  R --> P3[nobat<br/>HTML]
  R --> P4[drnext<br/>JSON API]
  R --> P5[darmankade<br/>JSON + __NEXT_DATA__]
  P1 & P2 & P3 & P4 & P5 --> H[util.http<br/>allowlist · retries · size cap]
  R --> G[report.js<br/>group same doctor]
  G --> M[Markdown report]
  G --> J[buildModel] --> T[html.js + report-template.html] --> F[(reports/*.html)]
src/
  index.js              stdio entry point: start server, graceful shutdown, crash logging
  server.js             MCP tools (schemas, annotations, output)
  search.js             platform registry, parallel search, per-site deadline, cache
  report.js             grouping, Markdown report, buildModel() for the HTML page
  html.js               render/save HTML (CSP hash, atomic write, pruning), open in browser
  report-template.html  the page: CSS + vanilla JS, data injected as JSON
  cli.js                terminal command
  config.js             environment configuration (validated)
  log.js                stderr JSON logger
  util.js               HTTP client, Persian text, Tehran time, Jalali calendar
  providers/            one module per booking site
test/
  unit/*.test.js        offline tests (node:test)
  helpers/              test env + synthetic fixtures (no real people)
  live.js               end-to-end test against the real sites over MCP stdio

Supported platforms

Platform

Name search

City search

First free time

Price

Source

پذیرش۲۴ paziresh24.com

✓

✓ /search/{slug}

✓ exact time

✓ Rial → Toman

JSON API

دکترتو doctoreto.com

✓

✓ citySlug=

✓ exact time

✓ online visits (office visit paid at clinic)

__NEXT_DATA__

نوبت nobat.ir

✓

✓ city in query

✓ day + clinic hours

✗ booking is free, paid at clinic

HTML

دکترنکست drnext.ir

✓

filtered on office city

✓ exact time

✓ Rial → Toman

JSON API

درمانکده darmankade.com

✓

✓ city=

✓ exact time

✓ Toman

JSON + __NEXT_DATA__

Checked and not added, because they don't offer the same "name → free time → price" search:

  • DoctorYab

  • Snapp Doctor

  • Tebinja

  • HiDoctor

  • the insurance portals that need a login

list_platforms shows the reasons.


Security and privacy

  • Network allowlist. The HTTP client fetches only paziresh24.com, doctoreto.com, nobat.ir, drnext.ir, darmankade.com and their subdomains, and checks again after redirects. User-supplied ids and URLs can't make the server request other hosts, including internal addresses (no SSRF).

  • Bounded work. Every request has a timeout, a retry limit and a response-size cap, and each platform has an overall deadline.

  • HTML page. Data is embedded as escaped JSON (it can't close its <script> block). The page is rendered with escaping, and a Content-Security-Policy lets only the page's own script run, pinned by its SHA-256 hash. The page can't send anything anywhere (default-src 'none', form-action 'none', no-referrer). Links accept only http(s) URLs.

  • What is stored. Nothing besides the HTML reports you ask for, in DOCTOR_MCP_REPORT_DIR, pruned automatically. Logs don't contain search terms. There are no accounts, no tokens and no telemetry.

  • Data source. Only public profile pages and public endpoints of the booking sites are read, the same data a visitor sees. Results are cached briefly to avoid repeated requests. Please keep request volumes modest.


Development

npm test             # offline unit tests (util, grouping/report, HTML safety, search resilience, MCP server)
npm run test:live    # real end-to-end run over MCP stdio:  node test/live.js "مریم احمدی" تهران
npm run check        # syntax check of every source file
npm run inspect      # MCP Inspector UI

What the offline tests cover:

  • Jalali calendar round-trips for every day from 2015 to 2035, Persian digits, name and city normalisation.

  • The URL allowlist.

  • Doctor grouping and every report section.

  • XSS attempts against the HTML page, the CSP hash, atomic save and pruning.

  • Per-site deadlines, error mapping and the cache.

  • The MCP tool list, input limits and the SSRF refusal.

Releasing:

  1. Bump version in package.json. The server reads its version from there.

  2. Add an entry to CHANGELOG.md.

  3. Run npm test && npm run test:live.


Adding a platform

Create src/providers/<id>.js exporting:

export const info = { id: "<id>", name: "نام فارسی", site: "https://…", app: "…", notes: "…" };

/** Doctors matching `name` (and `city`, if given), at most `limit`. */
export async function search(name, { city, limit }) { return [/* Doctor */]; }

/** One profile by id or profile URL. */
export async function details(id) { return /* Doctor */; }
type Doctor = {
  platform: string; platformName: string; id: string; name: string;
  specialty: string | null; city: string | null;
  rating: number | null; ratingCount: number | null; satisfaction: number | null;  // satisfaction in %
  insurances: string[]; profileUrl: string; notes: string[];
  services: Service[];
};
type Service = {
  type: "in_person" | "online" | "online_phone" | "online_text" | "online_video" | "online_audio";
  label: string;
  priceToman: number | null; priceNote: string | null;     // e.g. "حق ویزیت در مطب"
  firstFree: Date | null;                                    // a real instant (Tehran time handled by util.parseTehranLocal)
  firstFreeIsDayOnly?: boolean; firstFreeLabel: string | null; // label explains why there is no slot, or clinic hours
  center: string | null; address: string | null; phones: string[];
  bookingUrl: string; openDays?: { date: Date; hours: string | null }[];
};

Then:

  1. Register the module in PROVIDERS in src/search.js.

  2. Add the site's domain to ALLOWED_HOSTS in src/util.js.

  3. Add a colour token --s-<id> in report-template.html (light and dark) and the id to the SITES list there.

  4. Make sure search() uses util.http() and nameMatches() / cityMatches(), and that it throws on real failures. searchAll turns a failure into a status entry, so other platforms aren't affected.


Troubleshooting

Symptom

What to do

A site shows ✗ … پاسخ نداد (timeout / HTTP 403 / ENOTFOUND)

It's temporary or the site blocks your network; the other sites still work. Run with DOCTOR_MCP_LOG_LEVEL=debug to see the request. If one site keeps failing with parse errors, its page layout probably changed: update its provider.

configuration error: Invalid … and exit 78

Fix that environment variable (see Configuration).

The client doesn't list the tools

Check that node --version is ≥ 22 and that the path in the client config is absolute, then reconnect (/mcp in Claude Code). Logs go to the client's MCP log (stderr).

Times look shifted

Times are computed in Asia/Tehran (UTC+03:30, no DST since 2022). The HTML page uses the browser's Intl time-zone data.

Too many doctors with the same name

Pass city, or use the specialty chips on the HTML page.

HTML page has no font styling offline

It falls back to Tahoma/system fonts; everything else works offline.


Limitations

  • Unofficial endpoints. These are the sites' public web endpoints, not documented APIs. A site redesign can break its provider until it is updated. The other platforms keep working.

  • Live snapshots. Prices and free slots are read at search time and can change before you book. On Paziresh24 an office-visit price is the amount paid at booking. On nobat.ir only the day and the clinic hours are known.

  • Same-doctor merging is a heuristic (see How "same doctor" is decided).

  • Not medical advice. This tool finds appointments; it doesn't recommend doctors. In an emergency call 115.

Available Tools

3 tools
get_doctor_detailsجزئیات یک پزشک در یک پلتفرمA
Read-onlyIdempotent

Full details for ONE doctor on ONE platform: every visit type with price, first free time, clinic address & phones (and open days for nobat.ir). The id is the one shown in search_doctor JSON or the profile URL itself: paziresh24 = slug (دکتر-مریم-احمدی-5), doctoreto = 'slug/code' (dr-mehran-ahmadi/GxbEdZ), nobat = page slug or URL, drnext = doctor id (zvOqzwrOZ4BZ), darmankade = numeric id (423925). A full profile URL of that platform is accepted.

Inputs: id (required), platform (required).

list_platformsفهرست پلتفرم‌های نوبت‌دهیA
Read-onlyIdempotent

List the supported Iranian doctor booking platforms, what each provides, and which sites were checked but excluded (and why).

Inputs: no named parameters.

search_doctorجستجوی پزشک در اپ‌های نوبت‌دهی ایرانA
Idempotent

Search a doctor BY NAME across the 5 Iranian booking platforms that support name search + free appointment + price (Paziresh24 پذیرش۲۴, Doctoreto دکترتو, Nobat.ir نوبت, DrNext دکترنکست, Darmankade درمانکده). Returns a Persian report: summary, one block per doctor (profiles of the same person on different sites are merged) with first free time, price in Toman and booking links, best options, next steps and platform status. Also saves an interactive HTML page and returns its path: give that path to the user. Use Persian names (e.g. «مریم احمدی»); last name alone also works. ALWAYS pass city when the user mentions one: each platform is then searched inside that city, so local doctors are not crowded out.

Inputs: name (required), city, html, sort, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools occupy clearly separate roles: aggregate name search across platforms, deep-dive on a single doctor on a single platform, and static platform metadata. The descriptions explicitly state the boundary (search returns summaries/links; details requires one platform + id), so misselection is unlikely.

    Naming Consistency5/5

    All three follow a consistent verb_noun snake_case pattern: search_doctor, get_doctor_details, list_platforms. Verb choice (search/get/list) also maps cleanly to the operation type.

    Tool Count4/5

    Three tools is minimal but each earns its place for a search-aggregator domain, and the surface is not padded. It sits at the low end of the comfortable range, so an extra capability tool (e.g. search by specialty or city browse) would round it out.

    Completeness3/5

    Search→details→platform-info covers the discovery lifecycle, and booking links are returned, but search is name-only: there is no browse by specialty, city, or price filter, which are core user intents in doctor discovery. No booking/availability-query operation either, so the workflow dead-ends at an external link.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables finding doctors in Romania by county, speciality, language, name, and weekly availability, with fuzzy name matching and nearby-county fallback.
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables querying Doctolib's public data to find practitioners, retrieve all available appointment slots in a geographic area, access practice details, and receive alerts when new slots open.
      21
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search Iranian doctors, hospitals and clinics by specialty, city, name, gender and online visit, then read profiles, ratings, insurances, patient reviews, visit prices in Toman and free appointment times. Read-only, with no login, booking or payment, so users compare options and get a profile link to book themselves.
      12
      375 PyPI
      4
      PolyForm Noncommercial 1.0.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search Iranian doctors by speciality, city, neighborhood, insurance and visit type, compare office and online consultation fees, check free appointment times up to a month ahead, and read reviews. Also covers hospitals, clinics, labs, pharmacies, fixed-price clinic offers and health articles, all read-only so booking happens on the site via a returned link.
      14
      372 PyPI
      2
      PolyForm Noncommercial 1.0.0