FHIR MCP Server

Servidor FHIR MCP – que te ayuda a exponer cualquier servidor o API FHIR como un servidor MCP.

GitHub

137

Prueba este MCPPatrocinado

Documentación

Servidor Model Context Protocol (MCP) para APIs de Fast Healthcare Interoperability Resources (FHIR)

Tabla de Contenidos

Servidor Model Context Protocol (MCP) para APIs de Fast Healthcare Interoperability Resources (FHIR)

Descripción General

El Servidor FHIR MCP es un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona integración perfecta con APIs FHIR. Diseñado para desarrolladores, integradores e innovadores en salud, este servidor actúa como un puente entre herramientas modernas de IA/LLM y datos de salud, facilitando la búsqueda, recuperación y análisis de información clínica.

Demostración

Demostración con servidor HAPI FHIR

Este video muestra la funcionalidad del servidor MCP cuando se conecta a un servidor HAPI FHIR público. Este ejemplo muestra la interacción directa con un servidor FHIR abierto que no requiere un flujo de autorización.

https://github.com/user-attachments/assets/cc6ac87e-8329-4da4-a090-2d76564a3abf

Demostración con EPIC Sandbox

Este video muestra las capacidades del servidor MCP dentro del ecosistema Epic EHR. Demuestra el flujo completo de Concesión de Código de Autorización OAuth 2.0.

https://github.com/user-attachments/assets/96b433f1-3e53-4564-8466-65ab48d521de

Características Principales

Transporte compatible con MCP: Sirve FHIR a través de stdio, SSE o HTTP transmisible
Soporte de autenticación basado en SMART-on-FHIR: Autentica de forma segura con servidores y clientes FHIR
Filtrado de Respuestas usando FHIRPath: Filtra recursos y paquetes devueltos por operaciones read y search usando expresiones FHIRPath personalizadas para recuperar solo los campos necesarios para la tarea, reduciendo los tamaños de carga útil.
Integración de herramientas: Integrable con cualquier cliente MCP como VS Code, Claude Desktop y MCP Inspector

Requisitos Previos

Python 3.8+
uv (para gestión de dependencias)
Un servidor de API FHIR accesible.

Instalación

Puede usar el Servidor FHIR MCP instalando nuestro paquete de Python, o clonando este repositorio.

Instalación usando Paquete PyPI

Configurar Variables de Entorno:

Para ejecutar el servidor, debe establecer FHIR_SERVER_BASE_URL.
- Para habilitar la autorización: Establezca FHIR_SERVER_BASE_URL, FHIR_SERVER_CLIENT_ID, FHIR_SERVER_CLIENT_SECRET y FHIR_SERVER_SCOPES. La autorización está habilitada por defecto.
- Para deshabilitar la autorización: Establezca FHIR_SERVER_DISABLE_AUTHORIZATION a True.
Por defecto, el servidor MCP se ejecuta en http://localhost:8000, y puede personalizar el host y el puerto usando FHIR_MCP_HOST y FHIR_MCP_PORT.

Puede establecerlos exportándolos como variables de entorno como se muestra a continuación o creando un archivo .env (haciendo referencia a .env.example).
```
export FHIR_SERVER_BASE_URL=""
export FHIR_SERVER_CLIENT_ID=""
export FHIR_SERVER_CLIENT_SECRET=""
export FHIR_SERVER_SCOPES=""

export FHIR_MCP_HOST="localhost"
export FHIR_MCP_PORT="8000"
```
Instale el paquete PyPI y ejecute el servidor
```
uvx fhir-mcp-server
```

Instalación desde Código Fuente

Clone el repositorio:

git clone <repository_url>
cd <repository_directory>

Cree un entorno virtual e instale las dependencias:

uv venv
source .venv/bin/activate
uv pip sync requirements.txt

O con pip:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configurar Variables de Entorno: Copie el archivo de ejemplo y personalícelo si es necesario:
```
cp .env.example .env
```
Ejecute el servidor:
```
uv run fhir-mcp-server
```

Instalación usando Docker

Ejecutando el Servidor MCP con Docker

Puede ejecutar el servidor MCP usando Docker para un entorno consistente y aislado.

Nota sobre Autorización: Cuando se ejecuta el servidor MCP localmente a través de Docker o Docker Compose, la autorización debe deshabilitarse estableciendo la variable de entorno, FHIR_SERVER_DISABLE_AUTHORIZATION=True. Esto se corregirá en futuras versiones.

Construya la Imagen Docker o extraiga la imagen docker del registro de contenedores:
- Construir desde el código fuente:
```
docker build -t fhir-mcp-server .
```
- Extraer del Registro de Contenedores de GitHub:
```
docker pull wso2/fhir-mcp-server:latest
```
Configurar Variables de Entorno

Copie el archivo de entorno de ejemplo y edítelo según sea necesario:
```
cp .env.example .env
# Edit .env to set your FHIR server, client credentials, etc.
```
Alternativamente, puede pasar variables de entorno directamente con banderas -e o usar secretos de Docker para valores sensibles. Consulte la sección Configuración para detalles sobre las variables de entorno disponibles.
Ejecute el Contenedor
```
docker run --env-file .env -p 8000:8000 fhir-mcp-server
```
Esto iniciará el servidor y lo expondrá en el puerto 8000. Ajuste el mapeo de puertos según sea necesario.

Usando Docker Compose con Servidor HAPI FHIR

Para una configuración rápida que incluya tanto el servidor FHIR MCP como un servidor HAPI FHIR (con PostgreSQL), use el docker-compose.yml proporcionado. Esto configura un entorno de desarrollo instantáneo para probar operaciones FHIR.

Requisitos Previos:
- Docker y Docker Compose instalados.
Ejecute el Stack:
```
docker-compose up -d
```
Este comando:
- Iniciará un contenedor de base de datos PostgreSQL.
- Lanzará el servidor HAPI FHIR (conectado a PostgreSQL) escuchando en http://localhost:8080.
- Construirá y ejecutará el contenedor del servidor FHIR MCP escuchando en http://localhost:8000, con FHIR_SERVER_BASE_URL establecido a http://hapi-r4-postgresql:8080/fhir.
Acceda a los Servicios:
- Servidor FHIR MCP: http://localhost:8000
- Servidor HAPI FHIR: http://localhost:8080
- Para detener, ejecute docker-compose down.
Configurar Variables de Entorno Adicionales:

Si necesita personalizar OAuth u otras configuraciones, ajuste las variables de entorno en el docker-compose.yml. El archivo compose establece la configuración básica; consulte la sección Configuración para opciones completas.

Integración con Clientes MCP

El Servidor FHIR MCP está diseñado para una integración perfecta con varios clientes MCP.

VS Code

Agregue el siguiente bloque JSON a su archivo de configuración MCP en VS Code (> V1.104). Puede hacer esto presionando Ctrl + Shift + P y escribiendo MCP: Open User Configuration.

HTTP Transmisible STDIO SSE

HTTP Transmisible	STDIO	SSE
`"servers": { "fhir": { "type": "http", "url": "http://localhost:8000/mcp", } }`	`"servers": { "fhir": { "command": "uv", "args": [ "--directory", "/path/to/fhir-mcp-server", "run", "fhir-mcp-server", "--transport", "stdio" ], "env": { "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token" } } }`	`"servers": { "fhir": { "type": "sse", "url": "http://localhost:8000/sse", } }`

"servers": {
    "fhir": {
        "type": "http",
        "url": "http://localhost:8000/mcp",
    }
}

"servers": {
    "fhir": {
        "command": "uv",
        "args": [
            "--directory",
            "/path/to/fhir-mcp-server",
            "run",
            "fhir-mcp-server",
            "--transport",
            "stdio"
        ],
        "env": {
            "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
        }
    }
}

"servers": {
    "fhir": {
        "type": "sse",
        "url": "http://localhost:8000/sse",
    }
}

Claude Desktop

Agregue el siguiente bloque JSON a la configuración de su Claude Desktop para conectarse a su servidor MCP local.

Inicie la aplicación Claude Desktop, haga clic en el menú Claude en la barra superior y seleccione "Configuración…".
En el panel de Configuración, haga clic en "Desarrollador" en la barra lateral izquierda. Luego haga clic en "Editar Configuración". Esto abrirá su archivo de configuración en su sistema de archivos. Si aún no existe, Claude lo creará automáticamente en:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Abra el archivo claude_desktop_config.json en cualquier editor de texto. Reemplace su contenido con el siguiente bloque JSON para registrar el servidor MCP:

HTTP Transmisible STDIO SSE

HTTP Transmisible	STDIO	SSE
`{ "mcpServers": { "fhir": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:8000/mcp" ] } } }`	`{ "mcpServers": { "fhir": { "command": "uv", "args": [ "--directory", "/path/to/fhir-mcp-server", "run", "fhir-mcp-server", "--transport", "stdio" ], "env": { "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token" } } } }`	`{ "mcpServers": { "fhir": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:8000/sse" ] } } }`

{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/mcp"
            ]
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/fhir-mcp-server",
                "run",
                "fhir-mcp-server",
                "--transport",
                "stdio"
            ],
            "env": {
                "FHIR_SERVER_ACCESS_TOKEN": "Your FHIR Access Token"
            }
        }
    }
}

{
    "mcpServers": {
        "fhir": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:8000/sse"
            ]
        }
    }
}

MCP Inspector

Siga estos pasos para poner en funcionamiento el MCP Inspector:

Abra una terminal y ejecute el siguiente comando:

npx -y @modelcontextprotocol/inspector
En la interfaz del MCP Inspector:

HTTP Transmisible	STDIO	SSE
Tipo de Transporte: `Streamable HTTP` URL: `http://localhost:8000/mcp`	Tipo de Transporte: `STDIO` Comando: `uv` Argumentos: `--directory /path/to/fhir-mcp-server run fhir-mcp-server --transport stdio`	Tipo de Transporte: `SSE` URL: `http://localhost:8000/sse`

Asegúrese de que su servidor MCP ya esté ejecutándose y escuchando en el endpoint anterior.

Una vez conectado, MCP Inspector le permitirá visualizar invocaciones de herramientas, inspeccionar cargas útiles de solicitud/respuesta y depurar sus implementaciones de herramientas fácilmente.

Configuración

Opciones de CLI

Puede personalizar el comportamiento del servidor MCP usando las siguientes banderas de línea de comandos:

--transport
- Descripción: Especifica el protocolo de transporte utilizado por el servidor MCP para comunicarse con los clientes.
- Valores aceptados: stdio, sse, streamable-http
- Predeterminado: streamable-http
--log-level
- Descripción: Establece el nivel de verbosidad de registro para el servidor.
- Valores aceptados: DEBUG, INFO, WARN, ERROR (sin distinción de mayúsculas y minúsculas)
- Predeterminado: INFO
--help
- Descripción: Muestra un mensaje de ayuda con las opciones disponibles del servidor y sale.
- Uso: Proporcionado automáticamente por la interfaz de línea de comandos.

Ejemplos de Uso:

uv run fhir-mcp-server --transport streamable-http --log-level DEBUG
uv run fhir-mcp-server --help

Variables de Entorno

Configuraciones del Servidor MCP:

FHIR_MCP_HOST: El nombre de host o dirección IP al que el servidor MCP debe vincularse (por ejemplo, localhost para acceso solo local, o 0.0.0.0 para todas las interfaces).
FHIR_MCP_PORT: El puerto en el que el servidor MCP escuchará las solicitudes entrantes de los clientes (por ejemplo, 8000).
FHIR_MCP_SERVER_URL: Si se establece, este valor se usará como la URL base del servidor en lugar de generarla a partir del host y el puerto. Útil para configuraciones de URL personalizadas o cuando está detrás de un proxy.
FHIR_MCP_REQUEST_TIMEOUT: Duración del tiempo de espera en segundos para solicitudes del servidor MCP al servidor FHIR (predeterminado: 30).

Configuración OAuth2 del Servidor MCP con servidor FHIR (Cliente MCP ↔ Servidor MCP): Estas variables configuran la conexión segura del cliente MCP al servidor MCP, usando el flujo de concesión de código de autorización OAuth2 con un servidor FHIR.

FHIR_SERVER_CLIENT_ID: El ID de cliente OAuth2 utilizado para autorizar clientes MCP con el servidor FHIR.
FHIR_SERVER_DISABLE_AUTHORIZATION: Si se establece a True, deshabilita las verificaciones de autorización en el servidor MCP, permitiendo conexiones a servidores FHIR de acceso público.
FHIR_SERVER_CLIENT_SECRET: El secreto de cliente correspondiente al ID de cliente FHIR. Se usa durante el intercambio de tokens.
FHIR_SERVER_BASE_URL: La URL base del servidor FHIR (por ejemplo, https://hapi.fhir.org/baseR4). Esto se usa para generar URIs de herramientas y para enrutar solicitudes FHIR.
FHIR_SERVER_SCOPES: Una lista separada por espacios de alcances OAuth2 para solicitar al servidor de autorización FHIR (por ejemplo, user/Patient.read user/Observation.read). Agregue fhirUser openid para habilitar la recuperación del contexto del usuario para la herramienta get_user. Si estos dos alcances no están configurados, la herramienta get_user devuelve un resultado vacío porque el token de ID carece de la referencia de recurso FHIR del usuario.
FHIR_SERVER_ACCESS_TOKEN: El token de acceso para usar al autenticar solicitudes al servidor FHIR. Si esta variable está establecida, el servidor omitirá el flujo de autorización OAuth2 y usará este token directamente para todas las solicitudes.

[!NOTE] FHIR_SERVER_ACCESS_TOKEN está diseñada únicamente para implementaciones en modo stdio local, como una conveniencia para omitir la autenticación OAuth interactiva. No utilice esta variable cuando el servidor MCP esté expuesto a través de una red o de internet público.

Herramientas

get_capabilities: Recupera metadatos sobre un tipo de recurso FHIR específico, incluidos sus parámetros de búsqueda admitidos y operaciones personalizadas.
- type: El nombre del tipo de recurso FHIR (p. ej., "Patient", "Observation", "Encounter").
search: Ejecuta una interacción de búsqueda FHIR estándar en un tipo de recurso determinado, devolviendo un bundle o una lista de recursos coincidentes.
- type: El nombre del tipo de recurso FHIR (p. ej., "MedicationRequest", "Condition", "Procedure").
- searchParam: Una asignación de nombres de parámetros de búsqueda FHIR a sus valores deseados (p. ej., {"family":"Simpson","birthdate":"1956-05-12"}).
- response_filter_fhirpaths: (Opcional) Una matriz de expresiones FHIRPath (p. ej., ["Patient.name", "Patient.birthDate", "Bundle.link.where(relation='next').url"]) para aplicar a los recursos del bundle de respuesta.
read: Realiza una interacción de "lectura" FHIR para recuperar una única instancia de recurso por su tipo e ID de recurso, refinando opcionalmente la respuesta con parámetros de búsqueda u operaciones personalizadas.
- type: El nombre del tipo de recurso FHIR (p. ej., "DiagnosticReport", "AllergyIntolerance", "Immunization").
- id: El ID lógico de una instancia de recurso FHIR específica.
- searchParam: Una asignación de nombres de parámetros de búsqueda FHIR a sus valores deseados (p. ej., {"device-name":"glucometer"}).
- operation: El nombre de una operación FHIR personalizada o consulta extendida definida para el recurso (p. ej., "$everything").
- response_filter_fhirpaths: (Opcional) Una matriz de expresiones FHIRPath (p. ej., ["Patient.name", "Observation.valueQuantity"]) para filtrar el recurso único devuelto (o las entradas cuando se utilizan operaciones personalizadas como $everything).
create: Ejecuta una interacción de "creación" FHIR para persistir un nuevo recurso del tipo especificado.
- type: El nombre del tipo de recurso FHIR (p. ej., "Device", "CarePlan", "Goal").
- payload: Un objeto JSON que representa el cuerpo completo del recurso FHIR que se va a crear.
- searchParam: Una asignación de nombres de parámetros de búsqueda FHIR a sus valores deseados (p. ej., {"address-city":"Boston"}).
- operation: El nombre de una operación FHIR personalizada o consulta extendida definida para el recurso (p. ej., "$evaluate").
update: Realiza una interacción de "actualización" FHIR reemplazando el contenido de una instancia de recurso existente con la carga útil proporcionada.
- type: El nombre del tipo de recurso FHIR (p. ej., "Location", "Organization", "Coverage").
- id: El ID lógico de una instancia de recurso FHIR específica.
- payload: La representación JSON completa del recurso FHIR, que contiene todos los elementos requeridos y cualquier dato opcional.
- searchParam: Una asignación de nombres de parámetros de búsqueda FHIR a sus valores deseados (p. ej., {"patient":"Patient/54321","relationship":"father"}).
- operation: El nombre de una operación FHIR personalizada o consulta extendida definida para el recurso (p. ej., "$lastn").
delete: Ejecuta una interacción de "eliminación" FHIR en una instancia de recurso específica.
- type: El nombre del tipo de recurso FHIR (p. ej., "ServiceRequest", "Appointment", "HealthcareService").
- id: El ID lógico de una instancia de recurso FHIR específica.
- searchParam: Una asignación de nombres de parámetros de búsqueda FHIR a sus valores deseados (p. ej., {"category":"laboratory","issued:"2025-05-01"}).
- operation: El nombre de una operación FHIR personalizada o consulta extendida definida para el recurso (p. ej., "$expand").
get_user: Recupera el recurso FHIR del usuario autenticado actualmente (por ejemplo, el recurso Patient vinculado) y devuelve un perfil conciso que contiene campos demográficos disponibles como id, name y birthDate.

Desarrollo y Pruebas

Instalación de Dependencias de Desarrollo

Para ejecutar pruebas y contribuir al desarrollo, instale las dependencias de prueba:

Usando pip:

# Install project in development mode with test dependencies
pip install -e '.[test]'

# Or install from requirements file
pip install -r requirements-dev.txt

Usando uv:

# Install development dependencies
uv sync --dev

Ejecución de Pruebas

El proyecto incluye un conjunto completo de pruebas que cubre toda la funcionalidad principal:

# Simple test runner
python run_tests.py

# Or direct pytest usage
PYTHONPATH=src python -m pytest tests/ -v --cov=src/fhir_mcp_server

Usando pytest:

pytest tests/

Esto descubrirá y ejecutará todas las pruebas en el directorio tests/.

Características de las Pruebas:

Más de 100 pruebas con cobertura integral
Soporte completo de async/await usando pytest-asyncio
Simulación completa de solicitudes HTTP y dependencias externas
Informes de cobertura con salida en terminal y HTML
Ejecución rápida sin llamadas de red reales

El conjunto de pruebas incluye:

Pruebas unitarias: Pruebas de funcionalidad principal
Pruebas de integración: Validación de interacción entre componentes
Cobertura de casos límite: Escenarios de manejo de errores y validación
Flujos OAuth simulados: Pruebas de autenticación realistas

Los informes de cobertura se generan en htmlcov/index.html para un análisis detallado.