@ncodeuy/medplum-mcp

A Model Context Protocol (MCP) server that provides access to Medplum 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

npm install @ncodeuy/medplum-mcp

Configure

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

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

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):

{
  "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:

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

# 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