# 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.

```bash
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.

## Run locally

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

```bash
.venv/bin/python -m clinical_mcp.server
```

Use a different database file if needed:

```bash
.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:

```bash
.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`](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:

```json
{
  "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](SYNTHETIC_DATA.md) for the data guarantee.