FHIR MCP Server

An MCP (Model Context Protocol) 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 (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

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

Run it

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:

{
  "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, Solution Architect with 14+ years in enterprise software, cloud architecture, and — more recently — AI-assisted engineering, agents, and MCP servers.

License

MIT — see LICENSE.