# @ncodeuy/medplum-mcp

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that provides access to [Medplum](https://www.medplum.com/) FHIR healthcare data. It enables Claude and other MCP clients to read, search, and query FHIR resources from one or more Medplum environments.

## Features

- **Multi-environment support** — connect to multiple Medplum projects (e.g. dev, staging, production) and switch between them per request
- **30 FHIR resource types** — Patient, Practitioner, Observation, Condition, MedicationRequest, and more
- **Search with parameters** — query resources using standard FHIR search parameters
- **Resource history** — view version history of any resource with pagination

## Tools

The server exposes 5 MCP tools:

| Tool | Description |
|---|---|
| `fhir_get_environments` | List available Medplum environments and the default |
| `fhir_get_resource_types` | List supported FHIR resource types and their search parameters |
| `fhir_read` | Read a single FHIR resource by type and ID |
| `fhir_search` | Search for FHIR resources with query parameters |
| `fhir_read_history` | Get version history of a resource |

## Setup

### Install

```bash
npm install @ncodeuy/medplum-mcp
```

### Configure

Set one environment variable per field, using the pattern `MEDPLUM_PROJECT_<NAME>_<FIELD>`:

```bash
# Required
MEDPLUM_PROJECT_STAGING_CLIENT_ID=staging-client-id
MEDPLUM_PROJECT_STAGING_CLIENT_SECRET=staging-secret

# Optional (defaults to https://api.medplum.com/)
MEDPLUM_PROJECT_STAGING_BASE_URL=https://staging.example.com/
MEDPLUM_PROJECT_STAGING_PROJECT_ID=proj-staging

# Add more projects by changing the name segment
MEDPLUM_PROJECT_PRODUCTION_CLIENT_ID=prod-client-id
MEDPLUM_PROJECT_PRODUCTION_CLIENT_SECRET=prod-secret

# Optional — defaults to the first project found
MEDPLUM_DEFAULT_PROJECT=staging
```

<details>
<summary>Alternative: JSON configuration</summary>

You can also use the `MEDPLUM_PROJECTS` environment variable with a JSON object:

```bash
MEDPLUM_PROJECTS='{
  "staging": {
    "baseUrl": "https://staging.example.com/",
    "clientId": "staging-client-id",
    "clientSecret": "staging-secret",
    "projectId": "proj-staging"
  },
  "production": {
    "clientId": "prod-client-id",
    "clientSecret": "prod-secret"
  }
}'
```

Flat env vars take priority when both are set.

</details>

### Use with Claude Desktop

Add the server to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "medplum": {
      "command": "npx",
      "args": ["@ncodeuy/medplum-mcp"],
      "env": {
        "MEDPLUM_PROJECT_DEFAULT_CLIENT_ID": "your-client-id",
        "MEDPLUM_PROJECT_DEFAULT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### Use with Claude Code

Add the server to your Claude Code MCP settings:

```bash
claude mcp add medplum \
  -e MEDPLUM_PROJECT_DEFAULT_CLIENT_ID=your-client-id \
  -e MEDPLUM_PROJECT_DEFAULT_CLIENT_SECRET=your-client-secret \
  -- npx @ncodeuy/medplum-mcp
```

## Development

```bash
# Install dependencies
npm install

# Type check
npm run typecheck

# Run tests
npm test

# Build
npm run build

# Run the server locally
node ./dist/index.js
```

## License

ISC