simonlin1212/findadoctor

Important

Not medical advice. In an emergency, call 911 in the United States, 111 in New Zealand, or 15 (SAMU) or 112 in France.

Quick start

One address for every live country (the US, New Zealand and France):

https://api.findadoctor.si/mcp

Paste it into any MCP client that supports remote servers. There is no sign-in and no key. Or let your agent set it up; paste this into it:

Connect the FindADoctor.si MCP server to this client: https://api.findadoctor.si/mcp
(Streamable HTTP, no authentication; one address for the United States, New Zealand and France).
Read https://findadoctor.si/llms.txt first. If this client supports Agent Skills, also
install the findadoctor skill from
https://github.com/simonlin1212/findadoctor-mcp/tree/main/skills/findadoctor

Country first

• The agent decides the country first: where the person wants to see a doctor, from the place they mention or what it knows about where they live.
• If nothing settles it (no place given, or a place name used in more than one country, such as Hamilton, with no other clue), it asks the person before searching. It does not guess, and it does not search every country.
• Then it passes country (US, NZ or FR) to search_doctors, list_specialties and about_database. Doctor ids carry their country (dr_ = United States, nz_ = New Zealand, fr_ = France), so get_doctor needs no country.
• country is for MCP only. The HTTP APIs are per country, each on its own host, and take no country.
• Searches without country use the United States, so clients that connected before other countries were added work as before.
• Each country keeps its own daily allowance. New Zealand and France also have one-country addresses (details below: New Zealand, France).

Most of this page is about the United States; New Zealand and France have their own sections with their own tools.

❌ Without / ✅ With FindADoctor.si

Ask an agent that has only web search: "Who near Phoenix does a lot of AFib ablations? My father is 70." It has to piece an answer together from hospital marketing pages, review sites and directories:

• ❌ No way to tell who actually does the procedure often
• ❌ Rarely a check against the Medicare opt-out list or the federal exclusion list, which matters for a 70-year-old on Medicare
• ❌ A confident list that can't say where each claim came from

With FindADoctor.si, the same agent gets:

• ✅ Medicare 2024 procedure volumes with national ranks, for 81 procedure groups
• ✅ Focus areas from the doctor's own hospital-system page, as standard MeSH terms
• ✅ Registered specialty, medical school and hospital affiliations
• ✅ Warnings for the Medicare opt-out list and the OIG exclusion list
• ✅ A source and date on every evidence line, and phones that say where they came from

The database can't confirm insurance, and only some hospital pages list languages and new-patient status; each search reply tells the agent to check those on the web or with the office.

Try asking

Who near Phoenix does the most atrial fibrillation ablations? My father is 70.

My 9-year-old was just diagnosed with type 1 diabetes. We live in Houston.
Which pediatric endocrinologists focus on it?

Find rheumatologists within 10 miles of ZIP 60601 whose hospital pages say they speak Spanish.

More: "Is Dr. X really a hand surgeon, and where did they train?" · "Which knee replacement surgeons in Ohio have the highest Medicare volume?"

Connect

No sign-in, no API key. Point any MCP client that supports remote servers at the URL above; it covers the US, New Zealand and France.

Step-by-step instructions, with links to each client's own guide: docs/connect.md.

Install as a plugin

This repository is also a plugin: one install adds the MCP server and the findadoctor Agent Skill together.

Claude Code

claude plugin marketplace add simonlin1212/findadoctor-mcp
claude plugin install findadoctor@findadoctor

Codex CLI

codex plugin marketplace add simonlin1212/findadoctor-mcp
codex plugin add findadoctor@findadoctor

Gemini CLI

gemini extensions install https://github.com/simonlin1212/findadoctor-mcp

Other clients that read Agent Plugins can use plugin.json, mcp.json and skills/ from this repository.

How it works (United States)

Two steps:

1. search_doctors (over MCP with country: "US" or no country; the HTTP API takes no country): a free short list for a need (condition, procedure, specialty, place or name). It tells you who the doctors are and what evidence each one has, not the evidence itself.
2. get_doctor: the evidence for up to 10 doctors per call. This is counted per day, so open only the doctors you are seriously considering. One reply holds about 2–3 doctors; the rest come back under not_returned_yet, already counted, so ask again for them at no extra cost.

Every parameter: docs/tools.md and reference/tools.json (all tools at the one address, US, New Zealand and France). Every field of the US HTTP API: openapi.json.

Example

curl -s "https://api.findadoctor.si/api/v1/search?condition=atrial%20fibrillation&city=Phoenix&state=AZ&within_miles=25&medicare_patient=true"

Trimmed reply (names, ids, phones and addresses in this repository are made up):

{
  "total_matches": 436,
  "results": [
    {
      "rank": 1,
      "doctor_id": "dr_example00001",
      "name": "Jordan Example",
      "degree": "MD",
      "specialty": "Cardiac Electrophysiology",
      "city": "Phoenix",
      "state": "AZ",
      "distance_miles": 4.2,
      "match_basis": "direct_evidence",
      "detail_has": ["hospital_website_profile", "procedure_volume_for_this_need", "many_patients_with_this_condition", "phone", "new_patient_status", "languages"]
    }
  ],
  "next_step": "Call get_doctor with doctor_ids (up to 10 at once) for the doctors you are considering. …"
}

Then open the evidence:

curl -s "https://api.findadoctor.si/api/v1/doctors?ids=dr_example00001"

Full sample replies: examples/responses. Runnable examples: curl, Python, TypeScript.

Limits (United States)

As of 2026-10-13, during the public test. The current values are always on the Limits page.

• Searching does not count toward the doctor allowance. Opening the same doctor again the same UTC day is free.
• Connections from the Claude and ChatGPT apps, recognized by the network addresses Anthropic and OpenAI publish, have their own allowances (ChatGPT: 100 per user; Claude: one shared allowance for all its users). See /llms.txt.
• When the allowance runs out, the reply says so and when it resets (00:00 UTC). An agent should tell the person, not retry in a loop.
• Need more? Email contact@findadoctor.si with what your agent does to ask for an account key (sent as Authorization: Bearer). Keys are issued for the United States; through the one address, New Zealand and France use the allowance without an account.

Data (United States)

About 1.2 million US physicians with official records. About 280,000 of them also have facts from their hospital system's own website (about 82,000 with listed focus areas, as standard MeSH terms).

Sources: NPPES NPI registry, the CMS Doctors and Clinicians file, Medicare Physician & Other Practitioners 2024, Medicare Part D Prescribers 2024, CMS Open Payments 2024–2025, the CMS Provider Data Catalog, the OIG exclusion list, CMS Medicare opt-out affidavits, NLM MeSH, the NUCC taxonomy, the US Census Gazetteer, and hospital systems' own find-a-doctor pages. Every evidence line in a reply names its source and date. Details: Data and sources.

What it does not have:

• Insurance network checks. Confirm a plan on the insurer's directory or with the office.
• Appointment availability.
• Patient reviews or outcome measures for individual doctors. The only quality figure is the CMS MIPS 2024 score, usually reported for the whole practice group. Hospital affiliations show the CMS hospital star rating.
• Any patient records.

Rankings show evidence of focus and experience for a need, not quality of care. No private doctor rating, award or hospital ranking is included or counted. The hospital and children's hospital websites we read were chosen partly from published lists.

New Zealand

Through the one address, https://api.findadoctor.si/mcp, search with country: "NZ". get_doctor reads the country from the nz_ id, and search_gp_practices and public_waitlist are New Zealand only. No sign-up and the same two steps: a free short list, then evidence for the doctors you are considering.

There is also a New Zealand-only address, which needs no country:

https://api-nz.findadoctor.si/mcp

Use it if you want New Zealand alone, for example:

claude mcp add --transport http findadoctor-nz https://api-nz.findadoctor.si/mcp
codex mcp add findadoctor-nz --url https://api-nz.findadoctor.si/mcp
gemini mcp add --transport http findadoctor-nz https://api-nz.findadoctor.si/mcp

You don't need both addresses: the one address already covers New Zealand, and connecting both shows the agent the New Zealand tools twice. The plugins connect the one address.

The HTTP API is at https://api-nz.findadoctor.si. Every parameter: docs/tools.md (the one address, where these tools take country: "NZ"), docs/tools-nz.md and reference/tools-nz.json (the New Zealand-only address), and openapi.json. Docs: findadoctor.si/nz/docs/.

Try asking

I live in Christchurch and my GP says I may need a knee replacement. Which orthopaedic
surgeons focus on knees, and how long is the public wait?

We just moved to Lower Hutt. Which GP practices nearby are taking new patients, and what
do they charge for a 72-year-old?

What it has

• Every doctor on the Medical Council of New Zealand public register (about 21,000 practising), with scope of practice and, for most specialists, the year they became a specialist in New Zealand.
• About 7,800 doctors listed on Healthpoint with clinic addresses and phones: GPs, private specialists, and public-hospital doctors named on Health NZ service pages. About 1,200 of them list their own focus areas.
• About 1,000 general practices (whether they are taking new patients, fees by age) and urgent care clinics.
• Health NZ public waiting lists for 20 districts and 39 specialties.
• Seniority facts: New Zealand honours, University of Auckland academic titles and paper counts (Europe PMC).

Sources: Healthpoint, the Medical Council of New Zealand register, Health New Zealand | Te Whatu Ora waiting list data (CC BY 4.0), New Zealand honours lists, University of Auckland staff profiles and Europe PMC. Every fact comes with its source and read date. Details: Data and sources.

What it does not have: insurer cover (confirm with the insurer, often prior approval), appointment availability or private wait times, procedure volumes or outcomes for individual doctors, and clinic details for doctors who are only on the register (many public-hospital doctors and psychiatrists). Results are ordered by how directly the doctor's own listing matches the need. No ratings, reviews or rankings are used.

Limits: 5 different doctors opened with get_doctor per network address per day without an account, 30 requests a minute and 300 a day. Searches and GP practice lists don't count toward the doctor allowance. Each country counts separately, also through the one address. Current values: Limits.

France

Through the one address, https://api.findadoctor.si/mcp, search with country: "FR". get_doctor reads the country from the fr_ id, and hospital_procedure_volumes is France only. No sign-up and the same two steps: a free short list, then evidence for the doctors you are considering. Searches work in French or English.

There is also a France-only address, which needs no country:

https://api-fr.findadoctor.si/mcp

Use it if you want France alone, for example:

claude mcp add --transport http findadoctor-fr https://api-fr.findadoctor.si/mcp
codex mcp add findadoctor-fr --url https://api-fr.findadoctor.si/mcp
gemini mcp add --transport http findadoctor-fr https://api-fr.findadoctor.si/mcp

As with New Zealand, you don't need both addresses: the one address already covers France.

The HTTP API is at https://api-fr.findadoctor.si. Every parameter: docs/tools.md (the one address, where these tools take country: "FR"), docs/tools-fr.md and reference/tools-fr.json (the France-only address), and openapi.json. Docs: findadoctor.si/fr/docs/.

Try asking

J'habite à Bordeaux et je dois me faire opérer de la cataracte. Quels ophtalmologues près
de chez moi, et quelles cliniques en font le plus ?

I live in Nantes. Which rheumatologists nearby are in Secteur 1 (standard fees)?

What it has

• Every doctor in the RPPS register (about 267,000), plus about 8,100 found only in the Assurance Maladie directory, with specialty and practice addresses. 74% have a practice phone.
• The Assurance Maladie fee category (Secteur 1, Secteur 2 or OPTAM) for about 124,000 doctors, mostly in private practice.
• Official extra competences or university diplomas (DU/DIU) for about 49,000 doctors.
• About 10,000 doctors with a Maiia page or a page on one of six hospital websites; about 5,800 of them state their expertise or the procedures they offer.
• Open CCAM procedure volumes for about 1,600 hospital sites, 2021–2025.
• Industry declarations (Transparence Santé) matched to about 147,000 doctors. They appear only in a doctor's evidence, as declared, and are never used to rank or filter.

Sources: Annuaire Santé (RPPS register, Agence du Numérique en Santé, Licence Ouverte 2.0), the Assurance Maladie directory, Maiia and six hospital websites, Open CCAM (ATIH) and Transparence Santé (CC BY-NC-SA 4.0: no commercial use). Every fact comes with its source and read date. Details: Data and sources.

What it does not have: stated expertise for most doctors (few specialists state it in the sources we can read, and Doctolib and AP-HP pages are not included, so the agent should also search the web), appointment availability or waiting times, procedure volumes or outcomes for individual doctors, top-up insurance (mutuelle) cover, and patient reviews. Results are ordered by how directly the doctor's own data matches the need. No ratings, reviews or rankings are used, and industry links never change the order.

Limits: 5 different doctors opened with get_doctor per network address per day without an account, 30 requests a minute and 300 a day. Searches and hospital volumes don't count toward the doctor allowance. Current values: Limits.

Agent Skill

skills/findadoctor is an Agent Skill that tells an agent when and how to use the service. It covers what to ask the person, medicare_patient for anyone 65 or older, what to confirm before booking, and how to say what the data can't show. It works with the MCP tools or, without MCP, with the HTTP API. The plugins install it for you; otherwise copy the folder into ~/.agents/skills/ or your client's own skills folder (for Claude Code: ~/.claude/skills/).

What's in this repository

This is the official guide for connecting to the service, in the US, New Zealand and France. The server code and the database are not open source and are not in this repository.

Privacy

Search terms are used only to answer the request. They are not logged or stored, and they are not used to train AI models. Agents should not send a person's name, date of birth or insurance member ID. Full policy: Privacy.

Corrections, support and security

• Doctors: if something about you is wrong, see Corrections and removal for the United States, New Zealand or France. Please don't use GitHub issues for personal details.
• Bugs in replies, docs or examples: open an issue. Leave out anything about a patient.
• Security: see SECURITY.md.
• Email: contact@findadoctor.si

License

The contents of this repository (docs, examples, the Agent Skill, the plugin manifests) are MIT licensed. The license does not cover the service, its data, or the FindADoctor.si and Phoenix Tree names and logos. Use of the service and its data is governed by the Terms of use.

Operated by Phoenix Tree (Phoenix Tree AI).