FHIR MCP Server

Servidor FHIR MCP – ajudando você a expor qualquer Servidor ou API FHIR como um Servidor MCP.

GitHub

137

Experimente este MCPPatrocinado

Documentação

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

Sumário

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

Visão Geral

O FHIR MCP Server é um servidor Model Context Protocol (MCP) que fornece integração perfeita com APIs FHIR. Projetado para desenvolvedores, integradores e inovadores da área da saúde, este servidor atua como uma ponte entre ferramentas modernas de IA/LLM e dados de saúde, facilitando a busca, recuperação e análise de informações clínicas.

Demonstração

Demonstração com servidor HAPI FHIR

Este vídeo mostra a funcionalidade do servidor MCP quando conectado a um servidor HAPI FHIR público. Este exemplo demonstra a interação direta com um servidor FHIR aberto que não requer fluxo de autorização.

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

Demonstração com EPIC Sandbox

Este vídeo mostra as capacidades do servidor MCP dentro do ecossistema Epic EHR. Ele demonstra o fluxo completo de Concessão de Código de Autorização OAuth 2.0.

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

Principais Recursos

Transporte compatível com MCP: Atende FHIR via stdio, SSE ou HTTP transmissível
Suporte a autenticação baseada em SMART-on-FHIR: Autentique-se com segurança em servidores e clientes FHIR
Filtragem de Respostas usando FHIRPath: Filtre recursos e pacotes retornados pelas operações read e search usando expressões FHIRPath personalizadas para recuperar apenas os campos necessários para a tarefa, reduzindo o tamanho dos payloads.
Integração de ferramentas: Integrável com qualquer cliente MCP, como VS Code, Claude Desktop e MCP Inspector

Pré-requisitos

Python 3.8+
uv (para gerenciamento de dependências)
Um servidor de API FHIR acessível.

Instalação

Você pode usar o FHIR MCP Server instalando nosso pacote Python ou clonando este repositório.

Instalação usando Pacote PyPI

Configure as Variáveis de Ambiente:

Para executar o servidor, você deve definir FHIR_SERVER_BASE_URL.
- Para habilitar a autorização: Defina FHIR_SERVER_BASE_URL, FHIR_SERVER_CLIENT_ID, FHIR_SERVER_CLIENT_SECRET e FHIR_SERVER_SCOPES. A autorização é habilitada por padrão.
- Para desabilitar a autorização: Defina FHIR_SERVER_DISABLE_AUTHORIZATION como True.
Por padrão, o servidor MCP executa em http://localhost:8000, e você pode personalizar o host e a porta usando FHIR_MCP_HOST e FHIR_MCP_PORT.

Você pode defini-los exportando-os como variáveis de ambiente, como abaixo, ou criando um arquivo .env (referenciando .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 o pacote PyPI e execute o servidor
```
uvx fhir-mcp-server
```

Instalação a partir do Código-Fonte

Clone o repositório:

git clone <repository_url>
cd <repository_directory>

Crie um ambiente virtual e instale as dependências:

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

Ou com pip:

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

Configure as Variáveis de Ambiente: Copie o arquivo de exemplo e personalize se necessário:
```
cp .env.example .env
```
Execute o servidor:
```
uv run fhir-mcp-server
```

Instalação usando Docker

Executando o Servidor MCP com Docker

Você pode executar o servidor MCP usando Docker para um ambiente consistente e isolado.

Nota sobre Autorização: Ao executar o servidor MCP localmente via Docker ou Docker Compose, a autorização deve ser desabilitada definindo a variável de ambiente FHIR_SERVER_DISABLE_AUTHORIZATION=True. Isso será corrigido em versões futuras.

Construa a Imagem Docker ou baixe a imagem docker do registro de contêineres:
- Construir a partir do código-fonte:
```
docker build -t fhir-mcp-server .
```
- Baixar do GitHub Container Registry:
```
docker pull wso2/fhir-mcp-server:latest
```
Configure as Variáveis de Ambiente

Copie o arquivo de ambiente de exemplo e edite conforme necessário:
```
cp .env.example .env
# Edit .env to set your FHIR server, client credentials, etc.
```
Alternativamente, você pode passar variáveis de ambiente diretamente com flags -e ou usar segredos Docker para valores sensíveis. Consulte a seção Configuração para detalhes sobre as variáveis de ambiente disponíveis.
Execute o Contêiner
```
docker run --env-file .env -p 8000:8000 fhir-mcp-server
```
Isso iniciará o servidor e o exporá na porta 8000. Ajuste o mapeamento de portas conforme necessário.

Usando Docker Compose com Servidor HAPI FHIR

Para uma configuração rápida que inclui tanto o servidor FHIR MCP quanto um servidor HAPI FHIR (com PostgreSQL), use o docker-compose.yml fornecido. Isso configura um ambiente de desenvolvimento instantâneo para testar operações FHIR.

Pré-requisitos:
- Docker e Docker Compose instalados.
Execute a Pilha:
```
docker-compose up -d
```
Este comando irá:
- Iniciar um contêiner de banco de dados PostgreSQL.
- Iniciar o servidor HAPI FHIR (conectado ao PostgreSQL) escutando em http://localhost:8080.
- Construir e executar o contêiner do servidor FHIR MCP escutando em http://localhost:8000, com FHIR_SERVER_BASE_URL definido como http://hapi-r4-postgresql:8080/fhir.
Acesse os Serviços:
- Servidor FHIR MCP: http://localhost:8000
- Servidor HAPI FHIR: http://localhost:8080
- Para parar, execute docker-compose down.
Configure Variáveis de Ambiente Adicionais:

Se você precisar personalizar OAuth ou outras configurações, ajuste as variáveis de ambiente no docker-compose.yml. O arquivo compose define a configuração básica; consulte a seção Configuração para opções completas.

Integração com Clientes MCP

O FHIR MCP Server é projetado para integração perfeita com vários clientes MCP.

VS Code

Adicione o seguinte bloco JSON ao seu arquivo de configuração MCP no VS Code (> V1.104). Você pode fazer isso pressionando Ctrl + Shift + P e digitando MCP: Open User Configuration.

HTTP Transmissível STDIO SSE

HTTP Transmissível	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

Adicione o seguinte bloco JSON às configurações do seu Claude Desktop para conectar ao seu servidor MCP local.

Inicie o aplicativo Claude Desktop, clique no menu Claude na barra superior e selecione "Settings…".
No painel de Configurações, clique em "Developer" na barra lateral esquerda. Em seguida, clique em "Edit Config". Isso abrirá seu arquivo de configuração no sistema de arquivos. Se ele ainda não existir, o Claude o criará automaticamente em:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Abra o arquivo claude_desktop_config.json em qualquer editor de texto. Substitua seu conteúdo pelo seguinte bloco JSON para registrar o servidor MCP:

HTTP Transmissível STDIO SSE

HTTP Transmissível	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 estes passos para colocar o MCP Inspector em funcionamento:

Abra um terminal e execute o seguinte comando:

npx -y @modelcontextprotocol/inspector
Na interface do MCP Inspector:

HTTP Transmissível	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`

Certifique-se de que seu servidor MCP já esteja em execução e escutando no endpoint acima.

Uma vez conectado, o MCP Inspector permitirá que você visualize invocações de ferramentas, inspecione payloads de requisição/resposta e depure suas implementações de ferramentas facilmente.

Configuração

Opções de Linha de Comando

Você pode personalizar o comportamento do servidor MCP usando os seguintes flags de linha de comando:

--transport
- Descrição: Especifica o protocolo de transporte usado pelo servidor MCP para se comunicar com os clientes.
- Valores aceitos: stdio, sse, streamable-http
- Padrão: streamable-http
--log-level
- Descrição: Define o nível de verbosidade de registro para o servidor.
- Valores aceitos: DEBUG, INFO, WARN, ERROR (não sensível a maiúsculas/minúsculas)
- Padrão: INFO
--help
- Descrição: Exibe uma mensagem de ajuda com as opções disponíveis do servidor e sai.
- Uso: Fornecido automaticamente pela interface de linha de comando.

Exemplos de Uso:

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

Variáveis de Ambiente

Configurações do Servidor MCP:

FHIR_MCP_HOST: O nome do host ou endereço IP ao qual o servidor MCP deve vincular (por exemplo, localhost para acesso somente local, ou 0.0.0.0 para todas as interfaces).
FHIR_MCP_PORT: A porta na qual o servidor MCP escutará requisições de clientes recebidas (por exemplo, 8000).
FHIR_MCP_SERVER_URL: Se definido, este valor será usado como URL base do servidor em vez de ser gerado a partir do host e porta. Útil para configurações de URL personalizadas ou quando atrás de um proxy.
FHIR_MCP_REQUEST_TIMEOUT: Duração do timeout em segundos para requisições do servidor MCP ao servidor FHIR (padrão: 30).

Configuração OAuth2 do Servidor MCP com servidor FHIR (Cliente MCP ↔ Servidor MCP): Estas variáveis configuram a conexão segura do cliente MCP ao servidor MCP, usando o fluxo de concessão de código de autorização OAuth2 com um servidor FHIR.

FHIR_SERVER_CLIENT_ID: O ID do cliente OAuth2 usado para autorizar clientes MCP com o servidor FHIR.
FHIR_SERVER_DISABLE_AUTHORIZATION: Se definido como True, desabilita as verificações de autorização no servidor MCP, permitindo conexões a servidores FHIR publicamente acessíveis.
FHIR_SERVER_CLIENT_SECRET: O segredo do cliente correspondente ao ID do cliente FHIR. Usado durante a troca de tokens.
FHIR_SERVER_BASE_URL: A URL base do servidor FHIR (por exemplo, https://hapi.fhir.org/baseR4). Isso é usado para gerar URIs de ferramentas e para rotear requisições FHIR.
FHIR_SERVER_SCOPES: Uma lista separada por espaços de escopos OAuth2 a serem solicitados ao servidor de autorização FHIR (por exemplo, user/Patient.read user/Observation.read). Adicione fhirUser openid para habilitar a recuperação do contexto do usuário para a ferramenta get_user. Se esses dois escopos não estiverem configurados, a ferramenta get_user retorna um resultado vazio porque o token de ID não possui a referência de recurso FHIR do usuário.
FHIR_SERVER_ACCESS_TOKEN: O token de acesso a ser usado para autenticar requisições ao servidor FHIR. Se esta variável estiver definida, o servidor ignorará o fluxo de autorização OAuth2 e usará este token diretamente para todas as requisições.

[!NOTE] FHIR_SERVER_ACCESS_TOKEN destina-se apenas a implantações em modo stdio local, como uma conveniência para contornar a autenticação OAuth interativa. Não use esta variável quando o servidor MCP estiver exposto em uma rede ou na internet pública.

Ferramentas

get_capabilities: Recupera metadados sobre um tipo de recurso FHIR especificado, incluindo seus parâmetros de pesquisa suportados e operações personalizadas.
- type: O nome do tipo de recurso FHIR (por exemplo, "Patient", "Observation", "Encounter")
search: Executa uma interação de pesquisa FHIR padrão em um determinado tipo de recurso, retornando um bundle ou lista de recursos correspondentes.
- type: O nome do tipo de recurso FHIR (por exemplo, "MedicationRequest", "Condition", "Procedure").
- searchParam: Um mapeamento de nomes de parâmetros de pesquisa FHIR para seus valores desejados (por exemplo, {"family":"Simpson","birthdate":"1956-05-12"}).
- response_filter_fhirpaths: (Opcional) Uma matriz de expressões FHIRPath (por exemplo, ["Patient.name", "Patient.birthDate", "Bundle.link.where(relation='next').url"]) para aplicar aos recursos no bundle de resposta.
read: Executa uma interação de "leitura" FHIR para recuperar uma única instância de recurso pelo seu tipo e ID de recurso, opcionalmente refinando a resposta com parâmetros de pesquisa ou operações personalizadas.
- type: O nome do tipo de recurso FHIR (por exemplo, "DiagnosticReport", "AllergyIntolerance", "Immunization").
- id: O ID lógico de uma instância específica de recurso FHIR.
- searchParam: Um mapeamento de nomes de parâmetros de pesquisa FHIR para seus valores desejados (por exemplo, {"device-name":"glucometer"}).
- operation: O nome de uma operação FHIR personalizada ou consulta estendida definida para o recurso (por exemplo, "$everything").
- response_filter_fhirpaths: (Opcional) Uma matriz de expressões FHIRPath (por exemplo, ["Patient.name", "Observation.valueQuantity"]) para filtrar o único recurso retornado (ou entradas ao usar operações personalizadas como $everything).
create: Executa uma interação de "criação" FHIR para persistir um novo recurso do tipo especificado.
- type: O nome do tipo de recurso FHIR (por exemplo, "Device", "CarePlan", "Goal").
- payload: Um objeto JSON representando o corpo completo do recurso FHIR a ser criado.
- searchParam: Um mapeamento de nomes de parâmetros de pesquisa FHIR para seus valores desejados (por exemplo, {"address-city":"Boston"}).
- operation: O nome de uma operação FHIR personalizada ou consulta estendida definida para o recurso (por exemplo, "$evaluate").
update: Executa uma interação de "atualização" FHIR substituindo o conteúdo de uma instância de recurso existente pelo payload fornecido.
- type: O nome do tipo de recurso FHIR (por exemplo, "Location", "Organization", "Coverage").
- id: O ID lógico de uma instância específica de recurso FHIR.
- payload: A representação JSON completa do recurso FHIR, contendo todos os elementos obrigatórios e quaisquer dados opcionais.
- searchParam: Um mapeamento de nomes de parâmetros de pesquisa FHIR para seus valores desejados (por exemplo, {"patient":"Patient/54321","relationship":"father"}).
- operation: O nome de uma operação FHIR personalizada ou consulta estendida definida para o recurso (por exemplo, "$lastn").
delete: Executa uma interação de "exclusão" FHIR em uma instância de recurso específica.
- type: O nome do tipo de recurso FHIR (por exemplo, "ServiceRequest", "Appointment", "HealthcareService").
- id: O ID lógico de uma instância específica de recurso FHIR.
- searchParam: Um mapeamento de nomes de parâmetros de pesquisa FHIR para seus valores desejados (por exemplo, {"category":"laboratory","issued:"2025-05-01"}).
- operation: O nome de uma operação FHIR personalizada ou consulta estendida definida para o recurso (por exemplo, "$expand").
get_user: Recupera o recurso FHIR do usuário atualmente autenticado (por exemplo, o recurso Patient vinculado) e retorna um perfil conciso contendo campos demográficos disponíveis, como id, name e birthDate.

Desenvolvimento e Testes

Instalando Dependências de Desenvolvimento

Para executar os testes e contribuir com o desenvolvimento, instale as dependências de teste:

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

Executando Testes

O projeto inclui uma suíte de testes abrangente que cobre todas as funcionalidades principais:

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

Isso descobrirá e executará todos os testes no diretório tests/.

Recursos dos Testes:

Mais de 100 testes com cobertura abrangente
Suporte completo a async/await usando pytest-asyncio
Mocking completo de requisições HTTP e dependências externas
Relatórios de cobertura com saída em terminal e HTML
Execução rápida sem chamadas de rede reais

A suíte de testes inclui:

Testes unitários: Teste de funcionalidade principal
Testes de integração: Validação de interação entre componentes
Cobertura de casos extremos: Cenários de tratamento de erros e validação
Fluxos OAuth simulados: Teste de autenticação realista

Relatórios de cobertura são gerados em htmlcov/index.html para análise detalhada.