medplum-mcp

@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