iran-doctor-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@iran-doctor-mcp برای دکتر مریم احمدی در تهران زودترین نوبت و هزینه ویزیت را پیدا کن"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 ( |
Transport | MCP over stdio |
Tools |
|
Tests |
|
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.jsAfter 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 inspectThen 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 |
| string, 2–100 chars | — (required) | Doctor's name in Persian. Last name alone works. Titles («دکتر») and Arabic letters (ي/ك) are normalised. |
| string, ≤ 50 chars | — | Persian city name. Each platform is searched inside that city, so local doctors are not crowded out. |
| array | all | Subset of |
| 1–10 | 5 | How many matching doctors to open per platform. |
|
|
| Filter visit types in the report. |
|
|
| Order of doctors and options. |
| boolean |
| Append the raw structured results as JSON. |
| boolean |
| 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 |
| One of the platform ids. |
| The id from |
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:
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.
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.
Best options: soonest/cheapest in-person and online. When one option wins both, it is shown once («زودترین و ارزانترین نوبت حضوری»).
Next steps: pick the right doctor, where to book, the online fallback, try another site, phone the clinic, insurance and cancellation, emergency 115.
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 |
| Doctors to open per site (1–10, default 5). |
| Subset of platform ids. |
|
|
| Also print the Persian Markdown report. |
| Print the raw results as JSON (no HTML unless |
| Save HTML even with |
| 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.jsonConfiguration
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 |
|
| Timeout of one HTTP request (1000–120000). |
|
| Retries per request on network errors, timeouts, 429 and 5xx (0–5). Other 4xx responses are never retried. |
|
| Hard deadline for one platform's whole search. A slower site is reported as failed. |
|
| Max response body size (8 MB). |
|
| Seconds to cache identical searches (per platform). |
|
| Save an HTML page for every |
|
| Where HTML reports are written. The default is always writable, also for global / |
|
| Keep at most this many reports; the oldest are deleted. |
|
|
|
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 stdioSupported platforms
Platform | Name search | City search | First free time | Price | Source |
پذیرش۲۴ paziresh24.com | ✓ | ✓ | ✓ exact time | ✓ Rial → Toman | JSON API |
دکترتو doctoreto.com | ✓ | ✓ | ✓ exact time | ✓ online visits (office visit paid at clinic) |
|
نوبت 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 | ✓ | ✓ | ✓ exact time | ✓ Toman | JSON + |
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.comand 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 onlyhttp(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 UIWhat 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:
Bump
versioninpackage.json. The server reads its version from there.Add an entry to
CHANGELOG.md.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:
Register the module in
PROVIDERSinsrc/search.js.Add the site's domain to
ALLOWED_HOSTSinsrc/util.js.Add a colour token
--s-<id>inreport-template.html(light and dark) and the id to theSITESlist there.Make sure
search()usesutil.http()andnameMatches()/cityMatches(), and that it throws on real failures.searchAllturns a failure into a status entry, so other platforms aren't affected.
Troubleshooting
Symptom | What to do |
A site shows | It's temporary or the site blocks your network; the other sites still work. Run with |
| Fix that environment variable (see Configuration). |
The client doesn't list the tools | Check that |
Times look shifted | Times are computed in |
Too many doctors with the same name | Pass |
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 toolsget_doctor_detailsجزئیات یک پزشک در یک پلتفرمARead-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فهرست پلتفرمهای نوبتدهیARead-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جستجوی پزشک در اپهای نوبتدهی ایرانAIdempotent
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
Scored across 3 tools
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.
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.
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.
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
Related MCP Connectors
Web scraping and Iranian-web data tools for AI agents: JS rendering, proxies, Markdown output.
US doctors and providers by specialty, as one MCP tool through Apify
Book medical appointments with French doctors by specialty and city via AI agents.
Research 7,400+ US doctors: search, semantic search, profiles, reviews & procedure pricing.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables finding doctors in Romania by county, speciality, language, name, and weekly availability, with fuzzy name matching and nearby-county fallback.-
- AlicenseBqualityCmaintenanceEnables 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.21MIT
- AlicenseAqualityBmaintenanceEnables 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.12375 PyPI4PolyForm Noncommercial 1.0.0
- AlicenseAqualityBmaintenanceEnables 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.14372 PyPI2PolyForm Noncommercial 1.0.0