Clinical MCP

Clinical MCP is a local, SQLite-backed mock EHR exposed to Claude Desktop through the Model Context Protocol (MCP). It uses entirely synthetic data—no real PHI is present anywhere in this project.

MCP is a protocol that lets an AI client discover and call tools supplied by a local or remote server. This server uses the official Python SDK and stdio transport, so Claude Desktop launches it as a child process and exchanges structured tool messages over standard input/output.

Install and seed

Requires Python 3.10 or newer.

git clone https://github.com/karishmadhingra30/Clinical_MCP.git clinical-mcp
cd clinical-mcp
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
python data/seed.py
pytest

python data/seed.py replaces data/clinical_mcp.db with 40 reproducible synthetic patients. It deliberately includes two Nguyens, a patient with 12 encounters, a patient with five medications, and a patient with one encounter.

Related MCP server: Epic Patient API MCP Server

Run locally

The server is read-only by default. It writes protocol data only to stdout and log messages only to stderr.

.venv/bin/python -m clinical_mcp.server

Use a different database file if needed:

.venv/bin/python -m clinical_mcp.server --database /path/to/synthetic-ehr.db

To permit add_note to change the local synthetic database, opt in explicitly:

.venv/bin/python -m clinical_mcp.server --allow-writes

Even in read-only mode, add_note is advertised to the client and responds with a structured write_disabled error explaining how to enable it. In write mode it validates the patient, that the encounter belongs to that patient, note type, content length, and author before writing.

Connect Claude Desktop (macOS)

1. Copy claude_desktop_config.example.json into ~/Library/Application Support/Claude/claude_desktop_config.json (or merge its mcpServers entries into your existing file).

2. Replace both /ABSOLUTE/PATH/TO/clinical-mcp placeholders with the absolute path to this checkout. Keep the two variants if you want both a read-only and an explicitly write-enabled server; otherwise retain only one.

3. Restart Claude Desktop completely. The tools should appear under the connector/tools UI.

For connection problems, inspect Claude Desktop's server logs in ~/Library/Logs/Claude/ on macOS. The server itself also logs startup and unexpected failures to stderr; these are normally captured by Claude Desktop. A missing database generally means python data/seed.py was not run from this repository first.

Example prompts

• “Search the synthetic EHR for Nguyen and tell me which patient IDs are available.”

• “Show the demographics and record counts for patient 1.”

• “List patient 1’s last three encounters.”

• “Get notes for patient 1’s most recent encounter and summarize the plan.”

• “Show all medications, including ended ones, for patient 2.”

• “Add a synthetic progress note to patient 1’s encounter 1.” (requires the write-enabled configuration.)

Tool behavior

All tools return JSON structures with stable IDs so a client can chain calls. List tools return an empty list plus a useful message when no result matches; they cap results at 50 and mark capped responses. Broad note lists include a truncated flag if a body exceeds the 500-character preview length; repeat get_notes with that note's encounter_id to retrieve the full body. Errors always use:

{
  "error": {
    "code": "not_found",
    "message": "Patient '999' was not found.",
    "suggestion": "Try search_patients first to get a valid patient_id."
  }
}

The data-access layer in clinical_mcp/db.py uses raw, parameterized SQLite queries; no ORM is involved. See SYNTHETIC_DATA.md for the data guarantee.