# DoctorVerify — an MCP server for verifying Indian doctors

Verifies that someone claiming to be a registered Indian doctor actually is one, using
live data from the National Medical Commission — while staying honest about exactly
what's official, what's undocumented, and what's a manual fallback. Read "How
verification actually works here" before you use it; it's the most important part of
this README.

## What's here

| Primitive | Name | What it does |
|---|---|---|
| Tool | `search_doctor_registration` | Live search of the Indian Medical Register by name, registration number, State Medical Council, and/or year |
| Tool | `get_doctor_profile` | Live full profile (qualification, university, additional quals) for one match from a search |
| Tool | `check_blacklist` | Live check of NMC's current suspended/struck-off doctor list |
| Tool | `registration_lookup_guide` | Manual fallback: the exact official search steps, for when the live lookup fails or a match is ambiguous |
| Tool | `flag_lookalike_domain` | Checks a link against the official domain and known impersonators |
| Resource | `doctor-verification://official-sources` | The full landscape — individual lookup, the newer register, and the two sanctioned paths for automated checks at scale |
| Prompt | `verify_doctor_checklist` | A "verify this doctor properly" template chaining the live tools, then blacklist, then qualification match |

## How verification actually works here

**The official registry doesn't publish an API for third parties** — but it doesn't
need to, for this to work. The authoritative source is the National Medical
Commission's **Indian Medical Register (IMR)**, searchable by the public at
`nmc.org.in`. Its own search page calls a public, unauthenticated JSON endpoint
(`nmc.org.in/MCIRest/open/...`) directly from client-side JavaScript to render
results — found by reading that page's own script, not by guessing. `search_doctor_registration`,
`get_doctor_profile`, and `check_blacklist` call that same endpoint, so they return real
IMR data: registration, qualification, university, and current suspension status.

An earlier version of this README claimed `nmc.org.in`'s `robots.txt` disallows
automated access. That was checked and turned out to be wrong: the file at that path
isn't a standards-format robots.txt at all — it's a misconfigured Apache snippet
blocking a short list of named SEO crawlers (Ahrefs, Majestic, Semrush, ...) by
User-Agent, with no general `Disallow` directive. The Terms of Use don't prohibit this
either. That's what changed to make live verification here reasonable, where it wasn't
before.

**The honest caveat:** this endpoint is still undocumented and unsupported by NMC. It
could change shape, get rate-limited, or disappear without notice — there's no SLA,
versioning, or support contract behind it. Treat it as read-only, single-lookup
traffic, not a bulk pipeline (these tools cap result counts and never auto-paginate,
on purpose). `registration_lookup_guide` stays in the toolset specifically as the
fallback for when the live path breaks or a result looks wrong.

**A real trap worth knowing about:** while researching this, `nmcn.org.in` — one letter
off from the real `nmc.org.in` — turned up ranking for "verify Indian doctor" searches,
displaying IMR-style search content despite not being run by the National Medical
Commission. `flag_lookalike_domain` catches that one by name and flags anything else
unfamiliar as unreviewed rather than assuming it's safe. Always prefer typing
`nmc.org.in` yourself over clicking a link from a hospital, agent, or ad — and remember
a live-looking result can still come from a fake site.

**If you need automated verification at scale** — say, onboarding many doctors into a
health-tech platform rather than checking one by hand — there are two more paths, both
*officially sanctioned* (unlike the endpoint above), and both heavier than a weekend
project:

1. **Ayushman Bharat Digital Mission (ABDM), Healthcare Professional Registry (HPR).**
   The government's own digital-identity system for doctors, with a real, documented
   OAuth2 API and a sandbox at `sandbox.abdm.gov.in`. It's built for registering and
   confirming practitioners as part of an accredited health system integration (the M1
   module), not anonymous one-off lookups, so onboarding is a genuine integration
   project — client ID/secret, certification, the works.
2. **Commercial KYC/verification vendors** (e.g. Surepass, IDfy). Several companies
   resell NMC-backed doctor verification as a paid, supported API product. That can be
   the pragmatic choice for production use, but evaluate each vendor's actual data
   source, freshness, and terms yourself — this project doesn't endorse a specific one.

## Setup

Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).

```bash
./setup.sh
```

This is a proper installable package (`src/doctor_verify_mcp/`, `pyproject.toml`), not
just a loose script. `./setup.sh` runs `uv sync`, which creates `.venv` (pinned to
Python 3.10 via `.python-version`) and installs the package plus its `dev` dependency
group (`pytest`) in editable mode. Without `uv`, fall back to
`python3 -m venv .venv && source .venv/bin/activate && pip install -e '.[dev]'`
(add a `[dependency-groups]`-to-`[project.optional-dependencies]` mirror if your pip
version doesn't understand dependency groups yet).

## Run it

```bash
uv run mcp dev src/doctor_verify_mcp/server.py
```

Open the Inspector URL it prints. Try `search_doctor_registration` with just a name,
then narrow it with a registration number or `state_council`. Take a `doctor_id` from
the results and pass it to `get_doctor_profile`. Try `check_blacklist` with no
arguments to see the full current list. Try `flag_lookalike_domain` with `nmcn.org.in`
and with `nmc.org.in` and compare. Check the `doctor-verification://official-sources`
resource for the full picture in one place.

Once installed (editable or from a built wheel), the package also exposes a console
script that runs the server directly over stdio (no Inspector, for wiring into a real
host): `uv run doctor-verify-mcp`.

## Build it

```bash
uv build
```

Produces `dist/doctor_verify_mcp-<version>-py3-none-any.whl` and a matching `.tar.gz`
sdist, installable anywhere with `pip install dist/doctor_verify_mcp-*.whl`.

## Test it

```bash
uv run pytest
```

The tests for the three live tools mock the HTTP layer (`doctor_verify_mcp.server._http_client`)
with NMC's real response shapes captured during development, so the suite doesn't hit
`nmc.org.in` on every run.

## Connect it to a real host

Building an actual integration (e.g. wiring this into a doctor registration/onboarding
flow)? See [INTEGRATION.md](INTEGRATION.md) for the full tool reference, a recommended
verification flow, the error-handling contract, and known quirks of the live endpoint.

Same pattern as any local MCP server — a host runs your server as a child process over
stdio, so every host needs the same launch command with an **absolute path**. Once the
package is installed, the `doctor-verify-mcp` console script is the cleanest launch
target instead of pointing hosts at `server.py` directly.

**Claude Desktop:** `uv run mcp install src/doctor_verify_mcp/server.py`, then fully
quit and reopen the app.

**Claude Code:**
```bash
claude mcp add doctorverify -- uv run --with "mcp[cli]" mcp run /absolute/path/to/src/doctor_verify_mcp/server.py
```

**Cursor** (`.cursor/mcp.json`) and **VS Code** (`.vscode/mcp.json`) follow the same
`command`/`args` shape — see the previous project's README for the exact JSON if you
need a reminder.

## Extending this

- Add a tool that validates a registration number's *shape* once you know the format
  your state council actually uses — they vary enough across states that this project
  doesn't guess at one.
- Add more entries to `KNOWN_LOOKALIKES` as you encounter them.
- If the `MCIRest` endpoint ever changes shape or starts blocking automated traffic, the
  live tools already raise a clear error pointing back to `registration_lookup_guide`
  rather than failing silently — check there first before assuming a doctor doesn't
  exist.
- If you go the ABDM/HPR route, a `verify_hpr_id` tool that calls the real, documented
  API (with your own client credentials, never hardcoded in source) would give you a
  supported alternative to the undocumented endpoint this project uses today.
- Add a resource per State Medical Council with direct links, for the cases where the
  IMR doesn't show a result and the fallback is checking a specific state's council
  site directly.