# FHIR MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI assistants **safe, read-only access to healthcare data** using the FHIR R4 standard — built on a public sandbox, so it's completely safe to run, share, and extend.

Instead of an AI assistant guessing at what a "patient," "observation," or "condition" looks like, this server lets it query real FHIR-shaped data through a small set of well-defined, guardrailed tools.

> ⚠️ **Data note:** This project connects to the [SMART Health IT public sandbox](https://docs.smarthealthit.org/sandbox/) (`r4.smarthealthit.org`), which serves **synthetic, non-real test data** for development purposes. No real patient data is used or stored anywhere in this project. This is a technical demonstration of AI-assisted healthcare data workflows — **not a clinical or diagnostic tool.**

---

## Why this project exists

Healthcare data is one of the most valuable — and most sensitive — domains for AI to work in. Most public MCP examples connect AI to generic APIs (weather, GitHub, Slack). This one demonstrates something closer to real enterprise work: giving an AI assistant **controlled, read-only** access to structured clinical data, with the same instincts you'd want in a production system — least privilege, hard limits, and no write access at all.

It pairs naturally with an orchestrating agent: point an AI assistant (Claude, or any MCP-compatible client) at this server, and it can look up patients, pull their vitals, and summarize conditions in plain language — all through auditable, typed tool calls instead of free-form scraping.

---

## Tools

| Tool | What it does |
|---|---|
| `search_patients` | Search the sandbox for patients by name |
| `get_patient` | Get demographic details for a patient by id |
| `get_observations` | Get recent vitals/lab observations for a patient |
| `summarize_conditions` | Get a plain-language summary of a patient's recorded conditions |

All tools are **read-only** — there is no create, update, or delete capability anywhere in this server, by design.

---

## Guardrails

This server is built with the same discipline you'd want in any production integration:

- **Read-only, always.** No write, update, or delete operations exist in the codebase.
- **Result caps.** Every query is capped (default 10, max 20 results) to prevent runaway responses.
- **Request timeouts.** All outbound FHIR requests time out after 10 seconds.
- **Sandbox-only data source.** Points exclusively at a public, synthetic FHIR test server — never a production or real clinical system.

---

## Getting started

### Prerequisites
- Node.js 18+
- An MCP-compatible client (e.g. Claude Desktop, or any client supporting the MCP stdio transport)

### Install & build

```bash
git clone https://github.com/brianbastian01/fhir-mcp-server.git
cd fhir-mcp-server
npm install
npm run build
```

### Run it

```bash
npm start
```

The server communicates over stdio, so in practice you'll point your MCP client at it rather than running it standalone. For example, in Claude Desktop's config:

```json
{
  "mcpServers": {
    "fhir": {
      "command": "node",
      "args": ["/absolute/path/to/fhir-mcp-server/dist/index.js"]
    }
  }
}
```

Restart your MCP client, and the four tools above will be available for the AI to call.

### Try it

Once connected, ask your AI assistant something like:

> "Search the FHIR sandbox for patients named Smith, then summarize the conditions for the first result."

The assistant will call `search_patients`, then `summarize_conditions`, and give you a plain-language answer — all backed by real tool calls you can inspect.

---

## Project structure

```
fhir-mcp-server/
├── src/
│   └── index.ts       # Server setup + all four tool definitions
├── dist/               # Compiled output (generated by `npm run build`)
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md
```

---

## Roadmap / ideas for extending this

- Add a `medications` tool (FHIR `MedicationRequest` resource)
- Add pagination support for large result sets
- Add an in-memory cache to reduce repeated calls to the sandbox
- Swap the sandbox URL for a real FHIR server behind proper auth (OAuth2/SMART on FHIR) for a production-grade version
- Pair with a small orchestrating agent that chains these tools automatically

---

## About

Built by [Brian Bastian](https://www.linkedin.com/in/brianbastian01/), Solution Architect with 14+ years in enterprise software, cloud architecture, and — more recently — AI-assisted engineering, agents, and MCP servers.

## License

MIT — see [LICENSE](LICENSE).