@ncodeuy/medplum-mcp 0.1.0

package/dist/client-registry.d.ts

@@ -0,0 +1,11 @@
+import { MedplumClient } from "@medplum/core";
+import type { MedplumMcpConfig, ProjectConfig } from "./config.js";
+export declare class ClientRegistry {
+    private config;
+    private clients;
+    constructor(config: MedplumMcpConfig);
+    getClient(env?: string): MedplumClient;
+    envNames(): string[];
+    get defaultEnv(): string;
+    getProjectConfig(env?: string): ProjectConfig;
+}

package/dist/client-registry.js

@@ -0,0 +1,43 @@
+import { MedplumClient } from "@medplum/core";
+function createClientFromConfig(config) {
+    const client = new MedplumClient({
+        baseUrl: config.baseUrl,
+        cacheTime: 0,
+    });
+    client.setBasicAuth(config.clientId, config.clientSecret);
+    return client;
+}
+export class ClientRegistry {
+    config;
+    clients = new Map();
+    constructor(config) {
+        this.config = config;
+    }
+    getClient(env) {
+        const name = env || this.config.defaultProject;
+        const projectConfig = this.config.projects[name];
+        if (!projectConfig) {
+            throw new Error(`Unknown environment "${name}". Available: ${this.envNames().join(", ")}`);
+        }
+        let client = this.clients.get(name);
+        if (!client) {
+            client = createClientFromConfig(projectConfig);
+            this.clients.set(name, client);
+        }
+        return client;
+    }
+    envNames() {
+        return Object.keys(this.config.projects);
+    }
+    get defaultEnv() {
+        return this.config.defaultProject;
+    }
+    getProjectConfig(env) {
+        const name = env || this.config.defaultProject;
+        const projectConfig = this.config.projects[name];
+        if (!projectConfig) {
+            throw new Error(`Unknown environment "${name}". Available: ${this.envNames().join(", ")}`);
+        }
+        return projectConfig;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,3 @@
+import { MedplumClient } from "@medplum/core";
+/** Creates a Medplum client for read-only MCP operations using env-based auth. */
+export declare function createMedplumClient(): MedplumClient;

package/dist/client.js

@@ -0,0 +1,16 @@
+import { MedplumClient } from "@medplum/core";
+/** Creates a Medplum client for read-only MCP operations using env-based auth. */
+export function createMedplumClient() {
+    const baseUrl = process.env.MEDPLUM_BASE_URL;
+    const clientId = process.env.MEDPLUM_CLIENT_ID;
+    const clientSecret = process.env.MEDPLUM_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+        throw new Error("Missing MEDPLUM_CLIENT_ID or MEDPLUM_CLIENT_SECRET environment variables");
+    }
+    const client = new MedplumClient({
+        baseUrl: baseUrl || "https://api.medplum.com/",
+        cacheTime: 0,
+    });
+    client.setBasicAuth(clientId, clientSecret);
+    return client;
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export interface ProjectConfig {
+    baseUrl: string;
+    clientId: string;
+    clientSecret: string;
+    projectId?: string;
+}
+export interface MedplumMcpConfig {
+    projects: Record<string, ProjectConfig>;
+    defaultProject: string;
+}
+export declare function loadConfig(): MedplumMcpConfig;

package/dist/config.js

@@ -0,0 +1,53 @@
+export function loadConfig() {
+    const projectsJson = process.env.MEDPLUM_PROJECTS;
+    if (projectsJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(projectsJson);
+        }
+        catch {
+            throw new Error("MEDPLUM_PROJECTS contains invalid JSON. Expected a JSON object mapping environment names to project configs.");
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("MEDPLUM_PROJECTS must be a JSON object mapping environment names to project configs.");
+        }
+        const projects = {};
+        for (const [name, value] of Object.entries(parsed)) {
+            const cfg = value;
+            if (!cfg.clientId || !cfg.clientSecret) {
+                throw new Error(`Environment "${name}" is missing required clientId or clientSecret.`);
+            }
+            projects[name] = {
+                baseUrl: cfg.baseUrl || "https://api.medplum.com/",
+                clientId: cfg.clientId,
+                clientSecret: cfg.clientSecret,
+                projectId: cfg.projectId,
+            };
+        }
+        const keys = Object.keys(projects);
+        if (keys.length === 0) {
+            throw new Error("MEDPLUM_PROJECTS must contain at least one environment.");
+        }
+        const defaultProject = process.env.MEDPLUM_DEFAULT_PROJECT || keys[0];
+        if (!projects[defaultProject]) {
+            throw new Error(`MEDPLUM_DEFAULT_PROJECT "${defaultProject}" not found in MEDPLUM_PROJECTS. Available: ${keys.join(", ")}`);
+        }
+        return { projects, defaultProject };
+    }
+    // Legacy single-project fallback
+    const clientId = process.env.MEDPLUM_CLIENT_ID;
+    const clientSecret = process.env.MEDPLUM_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+        throw new Error("Missing MEDPLUM_PROJECTS or MEDPLUM_CLIENT_ID/MEDPLUM_CLIENT_SECRET environment variables.");
+    }
+    return {
+        projects: {
+            default: {
+                baseUrl: process.env.MEDPLUM_BASE_URL || "https://api.medplum.com/",
+                clientId,
+                clientSecret,
+            },
+        },
+        defaultProject: "default",
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ClientRegistry } from "./client-registry.js";
+import { loadConfig } from "./config.js";
+import { registerGetEnvironmentsTool } from "./tools/get-environments.js";
+import { registerGetResourceTypesTool } from "./tools/get-resource-types.js";
+import { registerReadHistoryTool } from "./tools/read-history.js";
+import { registerReadResourceTool } from "./tools/read-resource.js";
+import { registerSearchResourcesTool } from "./tools/search-resources.js";
+const server = new McpServer({
+    name: "medplum-fhir",
+    version: "0.1.0",
+});
+const config = loadConfig();
+const registry = new ClientRegistry(config);
+registerGetEnvironmentsTool(server, registry);
+registerReadResourceTool(server, registry);
+registerReadHistoryTool(server, registry);
+registerSearchResourcesTool(server, registry);
+registerGetResourceTypesTool(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/tools/get-environments.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ClientRegistry } from "../client-registry.js";
+export declare function registerGetEnvironmentsTool(server: McpServer, registry: ClientRegistry): void;

package/dist/tools/get-environments.js

@@ -0,0 +1,21 @@
+export function registerGetEnvironmentsTool(server, registry) {
+    server.tool("fhir_get_environments", "List available Medplum environments and which is the default. Call this first to discover environments before using other tools.", async () => {
+        const environments = registry.envNames().map((name) => {
+            const config = registry.getProjectConfig(name);
+            return {
+                name,
+                baseUrl: config.baseUrl,
+                projectId: config.projectId,
+                isDefault: name === registry.defaultEnv,
+            };
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ environments, default: registry.defaultEnv }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/get-resource-types.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGetResourceTypesTool(server: McpServer): void;

package/dist/tools/get-resource-types.js

@@ -0,0 +1,320 @@
+const RESOURCE_TYPES = [
+    {
+        resourceType: "Patient",
+        description: "Demographics and administrative information about a patient",
+        searchParams: [
+            "name",
+            "family",
+            "given",
+            "birthdate",
+            "gender",
+            "identifier",
+            "email",
+            "phone",
+            "address",
+            "active",
+            "organization",
+        ],
+    },
+    {
+        resourceType: "Practitioner",
+        description: "A person who is involved in the healthcare process",
+        searchParams: [
+            "name",
+            "family",
+            "given",
+            "identifier",
+            "email",
+            "phone",
+            "active",
+        ],
+    },
+    {
+        resourceType: "PractitionerRole",
+        description: "Roles/locations/specialties a practitioner may perform at an organization",
+        searchParams: [
+            "practitioner",
+            "organization",
+            "role",
+            "specialty",
+            "active",
+        ],
+    },
+    {
+        resourceType: "Organization",
+        description: "A formally or informally recognized grouping of people or organizations",
+        searchParams: ["name", "identifier", "type", "active", "address"],
+    },
+    {
+        resourceType: "Encounter",
+        description: "An interaction between a patient and healthcare provider(s)",
+        searchParams: [
+            "patient",
+            "status",
+            "class",
+            "date",
+            "type",
+            "participant",
+            "subject",
+        ],
+    },
+    {
+        resourceType: "Observation",
+        description: "Measurements and assertions about a patient or other subject",
+        searchParams: [
+            "patient",
+            "subject",
+            "code",
+            "category",
+            "date",
+            "status",
+            "value-concept",
+            "value-quantity",
+        ],
+    },
+    {
+        resourceType: "Condition",
+        description: "Detailed information about conditions or diagnoses",
+        searchParams: [
+            "patient",
+            "subject",
+            "code",
+            "clinical-status",
+            "category",
+            "onset-date",
+            "recorded-date",
+        ],
+    },
+    {
+        resourceType: "MedicationRequest",
+        description: "An order or request for medication",
+        searchParams: [
+            "patient",
+            "subject",
+            "status",
+            "intent",
+            "medication",
+            "encounter",
+            "date",
+        ],
+    },
+    {
+        resourceType: "AllergyIntolerance",
+        description: "Risk of harmful or undesirable response to a substance",
+        searchParams: [
+            "patient",
+            "clinical-status",
+            "type",
+            "category",
+            "code",
+            "date",
+        ],
+    },
+    {
+        resourceType: "Procedure",
+        description: "An action performed on or for a patient",
+        searchParams: [
+            "patient",
+            "subject",
+            "code",
+            "status",
+            "date",
+            "encounter",
+        ],
+    },
+    {
+        resourceType: "DiagnosticReport",
+        description: "Findings and interpretation of diagnostic tests",
+        searchParams: [
+            "patient",
+            "subject",
+            "code",
+            "category",
+            "status",
+            "date",
+            "encounter",
+        ],
+    },
+    {
+        resourceType: "ServiceRequest",
+        description: "A request for a procedure, diagnostic, or other service",
+        searchParams: [
+            "patient",
+            "subject",
+            "status",
+            "intent",
+            "code",
+            "encounter",
+            "occurrence",
+        ],
+    },
+    {
+        resourceType: "CarePlan",
+        description: "Healthcare plan for a patient or group",
+        searchParams: [
+            "patient",
+            "subject",
+            "status",
+            "category",
+            "date",
+            "encounter",
+        ],
+    },
+    {
+        resourceType: "CareTeam",
+        description: "Participants involved in the care of a patient",
+        searchParams: [
+            "patient",
+            "subject",
+            "status",
+            "participant",
+            "category",
+        ],
+    },
+    {
+        resourceType: "Appointment",
+        description: "A booking of a healthcare event",
+        searchParams: [
+            "patient",
+            "status",
+            "date",
+            "practitioner",
+            "actor",
+            "service-type",
+        ],
+    },
+    {
+        resourceType: "Schedule",
+        description: "A container for slots of time available for booking",
+        searchParams: ["actor", "date", "active", "service-type"],
+    },
+    {
+        resourceType: "Slot",
+        description: "A slot of time on a schedule available for booking",
+        searchParams: ["schedule", "status", "start"],
+    },
+    {
+        resourceType: "Task",
+        description: "A task to be performed",
+        searchParams: [
+            "patient",
+            "subject",
+            "status",
+            "owner",
+            "code",
+            "focus",
+            "encounter",
+        ],
+    },
+    {
+        resourceType: "Communication",
+        description: "A clinical or administrative communication",
+        searchParams: [
+            "patient",
+            "subject",
+            "status",
+            "category",
+            "sender",
+            "recipient",
+        ],
+    },
+    {
+        resourceType: "DocumentReference",
+        description: "A reference to a document of any kind",
+        searchParams: [
+            "patient",
+            "subject",
+            "status",
+            "type",
+            "category",
+            "date",
+        ],
+    },
+    {
+        resourceType: "Questionnaire",
+        description: "A structured set of questions",
+        searchParams: ["name", "title", "status", "code", "url"],
+    },
+    {
+        resourceType: "QuestionnaireResponse",
+        description: "A response to a questionnaire",
+        searchParams: [
+            "patient",
+            "subject",
+            "questionnaire",
+            "status",
+            "authored",
+        ],
+    },
+    {
+        resourceType: "Subscription",
+        description: "Server push notification channel",
+        searchParams: ["status", "type", "url", "criteria"],
+    },
+    {
+        resourceType: "Coverage",
+        description: "Insurance or medical plan or payment agreement",
+        searchParams: [
+            "patient",
+            "beneficiary",
+            "status",
+            "type",
+            "payor",
+        ],
+    },
+    {
+        resourceType: "Consent",
+        description: "A healthcare consumer's choices/agreements",
+        searchParams: [
+            "patient",
+            "status",
+            "category",
+            "date",
+        ],
+    },
+    {
+        resourceType: "Goal",
+        description: "Describes the intended objective(s) for a patient",
+        searchParams: [
+            "patient",
+            "subject",
+            "lifecycle-status",
+            "category",
+            "target-date",
+        ],
+    },
+    {
+        resourceType: "Immunization",
+        description: "Immunization event information",
+        searchParams: [
+            "patient",
+            "status",
+            "vaccine-code",
+            "date",
+        ],
+    },
+    {
+        resourceType: "Composition",
+        description: "A set of resources composed into a single coherent clinical statement",
+        searchParams: [
+            "patient",
+            "subject",
+            "type",
+            "status",
+            "date",
+            "encounter",
+        ],
+    },
+];
+export function registerGetResourceTypesTool(server) {
+    server.tool("fhir_get_resource_types", "List available FHIR resource types and their common search parameters", async () => {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(RESOURCE_TYPES, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/read-history.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ClientRegistry } from "../client-registry.js";
+export declare function registerReadHistoryTool(server: McpServer, registry: ClientRegistry): void;

package/dist/tools/read-history.js

@@ -0,0 +1,46 @@
+import { z } from "zod";
+const DEFAULT_COUNT = 20;
+const MAX_COUNT = 100;
+export function registerReadHistoryTool(server, registry) {
+    server.tool("fhir_read_history", "Read the version history of a FHIR resource by type and ID. Returns a Bundle of historical versions ordered from most recent to oldest.", {
+        resourceType: z
+            .string()
+            .describe("FHIR resource type (e.g. Patient, Practitioner, Organization)"),
+        id: z.string().describe("The resource ID"),
+        count: z
+            .number()
+            .optional()
+            .describe(`Number of history entries to return (default ${DEFAULT_COUNT}, max ${MAX_COUNT})`),
+        offset: z
+            .number()
+            .optional()
+            .describe("Number of history entries to skip (for pagination)"),
+        env: z
+            .string()
+            .optional()
+            .describe("Environment name to use. Omit for the default environment. Use fhir_get_environments to list available environments."),
+    }, async ({ resourceType, id, count, offset, env }) => {
+        try {
+            const medplum = registry.getClient(env);
+            const effectiveCount = Math.min(count ?? DEFAULT_COUNT, MAX_COUNT);
+            const bundle = await medplum.readHistory(resourceType, id, { count: effectiveCount, offset });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(bundle, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error reading history for ${resourceType}/${id}: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/read-resource.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ClientRegistry } from "../client-registry.js";
+export declare function registerReadResourceTool(server: McpServer, registry: ClientRegistry): void;

package/dist/tools/read-resource.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+export function registerReadResourceTool(server, registry) {
+    server.tool("fhir_read", "Read a single FHIR resource by type and ID", {
+        resourceType: z
+            .string()
+            .describe("FHIR resource type (e.g. Patient, Practitioner, Organization)"),
+        id: z.string().describe("The resource ID"),
+        env: z
+            .string()
+            .optional()
+            .describe("Environment name to use. Omit for the default environment. Use fhir_get_environments to list available environments."),
+    }, async ({ resourceType, id, env }) => {
+        try {
+            const medplum = registry.getClient(env);
+            const resource = await medplum.readResource(resourceType, id);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(resource, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error reading ${resourceType}/${id}: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/search-resources.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ClientRegistry } from "../client-registry.js";
+export declare function registerSearchResourcesTool(server: McpServer, registry: ClientRegistry): void;

package/dist/tools/search-resources.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+const DEFAULT_COUNT = 20;
+const MAX_COUNT = 100;
+export function registerSearchResourcesTool(server, registry) {
+    server.tool("fhir_search", "Search for FHIR resources with query parameters. Use fhir_get_resource_types to discover available types and search params.", {
+        resourceType: z
+            .string()
+            .describe("FHIR resource type to search (e.g. Patient, Observation)"),
+        params: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe("Search parameters as key-value pairs (e.g. { \"name\": \"John\", \"birthdate\": \"1990-01-01\" })"),
+        count: z
+            .number()
+            .optional()
+            .describe(`Number of results to return (default ${DEFAULT_COUNT}, max ${MAX_COUNT})`),
+        env: z
+            .string()
+            .optional()
+            .describe("Environment name to use. Omit for the default environment. Use fhir_get_environments to list available environments."),
+    }, async ({ resourceType, params, count, env }) => {
+        try {
+            const medplum = registry.getClient(env);
+            const searchParams = new URLSearchParams();
+            if (params) {
+                for (const [key, value] of Object.entries(params)) {
+                    searchParams.set(key, value);
+                }
+            }
+            const effectiveCount = Math.min(count ?? DEFAULT_COUNT, MAX_COUNT);
+            searchParams.set("_count", String(effectiveCount));
+            const bundle = await medplum.search(resourceType, searchParams);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(bundle, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error searching ${resourceType}: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@ncodeuy/medplum-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "medplum-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@medplum/core": "^5.0.15",
+    "@medplum/fhirtypes": "^5.0.15",
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.0.5"
+  }
+}