MCP CNES

Servidor MCP local para consultar dados públicos do Cadastro Nacional de Estabelecimentos de Saúde (CNES) e transformar registros hospitalares em recortes úteis para pesquisa, qualificação de leads e exportação para CRM.

O MCP CNES usa fontes oficiais do Ministério da Saúde/DATASUS, funciona por stdio, não exige chave de API e expõe 23 ferramentas MCP.

O que você pode fazer

• localizar hospitais por município, UF, tipo, gestão, natureza jurídica e porte;

• consultar razão social, CNPJ, mantenedora, endereço e contatos institucionais;

• diferenciar leitos de UTI, cirúrgicos, clínicos, obstétricos e complementares;

• identificar redes hospitalares pelo CNPJ da mantenedora;

• detectar expansão, retração, entrada e saída entre competências;

• calcular scores comerciais com pesos informados em cada chamada;

• exportar seleções auditáveis em CSV, JSON, JSONL ou XLSX;

• manter lotes históricos para comparação sem misturar competências.

O CNES descreve capacidade instalada. O projeto não calcula nem estima taxa de ocupação. CPF e nomes de pessoas físicas não fazem parte dos schemas, retornos ou arquivos exportados.

Related MCP server: cid10-br-mcp

Início rápido

O primeiro objetivo é fazer o cliente MCP listar as ferramentas e executar uma consulta real. O fluxo completo é:

instalar Git e uv
  → clonar o repositório
  → sincronizar o ambiente
  → configurar o cliente MCP
  → carregar uma competência
  → consultar hospitais

A versão 0.1.2 é distribuída pelo GitHub. PyPI, npm e instalação própria por curl ainda não são canais oficiais; por enquanto, use o checkout conforme as instruções abaixo.

Requisitos do sistema

• Windows 10/11, macOS ou Linux;

• Git;

• uv 0.12 ou superior;

• acesso HTTPS ao Portal SUS e acesso FTP ao DATASUS para a base completa;

• espaço em disco compatível com os arquivos consultados.

O runtime suporta Python 3.11 ou superior. O arquivo .python-version seleciona Python 3.14 para desenvolvimento, e o uv pode provisionar essa versão sem alterar o Python global do sistema.

Arquivos da base completa podem ser grandes. O limite de download padrão dessa fonte é 2 GiB; escolha um diretório com espaço livre suficiente antes da primeira carga.

Setup no sistema

Instalar o uv

No Windows, instale o Git pelo site oficial ou pelo gerenciador de pacotes da sua organização. Depois, em PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

No macOS ou Linux, instale o Git pelo gerenciador do sistema e execute:

curl -LsSf https://astral.sh/uv/install.sh | sh

Abra um novo terminal caso uv ainda não esteja no PATH.

Instalar a versão estável

Os mesmos comandos funcionam em PowerShell, macOS e Linux:

git --version
uv --version

git clone --branch v0.1.2 --depth 1 https://github.com/kevyn-castelo/mcp-cnes.git
cd mcp-cnes
uv sync --locked
uv run python --version

Para contribuir ou testar alterações ainda não lançadas, clone main sem --branch e sem --depth 1.

O comando uv sync --locked recria o ambiente a partir de pyproject.toml e uv.lock. Não reutilize a .venv copiada de outra máquina.

Verificar o servidor

No diretório do projeto, execute:

uv run mcp-cnes

O processo utiliza stdio e fica aguardando um cliente MCP. Um terminal sem prompt ou mensagens após a inicialização é esperado. Pressione Ctrl+C para encerrar o teste manual.

Configurar no cliente MCP

Adicione um servidor chamado cnes na configuração do seu cliente. Substitua CAMINHO_ABSOLUTO pelo diretório do checkout.

{
  "mcpServers": {
    "cnes": {
      "command": "uv",
      "args": [
        "--directory",
        "CAMINHO_ABSOLUTO",
        "run",
        "mcp-cnes"
      ]
    }
  }
}

Se o cliente não encontrar uv, substitua "command": "uv" pelo caminho absoluto retornado na última coluna.

Salve a configuração e reinicie completamente o cliente MCP. O nome e a localização do arquivo de configuração variam entre Claude Desktop, Cursor, VS Code, Codex e outros clientes; consulte a documentação do cliente para localizar a seção mcpServers.

Configuração de dados e armazenamento

Sem configuração adicional, bancos, caches e arquivos remotos ficam sob downloads/ dentro do checkout. Para separar código e dados, adicione um bloco env ao servidor já configurado:

{
  "env": {
    "MCP_CNES_COLUMNAR_DATABASE_PATH": "C:/dados/mcp-cnes/cnes.duckdb",
    "MCP_CNES_COLUMNAR_DIR": "C:/dados/mcp-cnes/parquet",
    "MCP_CNES_OUTPUT_DIR": "C:/dados/mcp-cnes/exports"
  }
}

Use caminhos absolutos equivalentes em macOS ou Linux. Configure também os diretórios de importação, download e cache da tabela abaixo quando quiser manter todos os dados fora do checkout.

O arquivo .env.example serve como referência, mas o entrypoint não o carrega automaticamente: defina as variáveis no cliente MCP ou no ambiente do processo.

Variáveis mais úteis

Para importação manual, MCP_CNES_ALLOWED_CSV_FILES pode restringir os nomes aceitos, separados por vírgula. Arquivos fora de MCP_CNES_DATA_DIR, links que escapem desse diretório e CSVs acima do limite são rejeitados antes da leitura.

Configurações inválidas interrompem a inicialização com erro explícito, antes de qualquer download ou processamento.

Fazer a primeira consulta

Depois de reiniciar o cliente, experimente esta sequência em linguagem natural.

1. Verificar as fontes

Liste as fontes disponíveis no MCP CNES e informe o status de cada uma.

O cliente deve chamar cnes_list_sources e mostrar:

• portal_sus_hospitais_leitos, para o contrato v1;

• datasus_base_completa, para o contrato v2.

Uma fonte externa indisponível aparece como indisponivel, com o motivo. O servidor não transforma falhas de rede em respostas vazias.

2. Descobrir uma competência

Liste as competências do Portal SUS para 2025.

O cliente deve usar cnes_list_competencias com ano=2025 e devolver competências mensais no formato YYYYMM.

3. Carregar os dados

Carregue a competência 202512 do Portal SUS para o Amazonas e deixe o lote ativo.

O cliente deve chamar cnes_fetch com algo equivalente a:

{
  "competencia": "202512",
  "uf": "AM",
  "fonte": "portal_sus_hospitais_leitos",
  "auto_load": true
}

A resposta informa lote_id, quantidade de registros, filtros locais, ETag e se o download usou cache. A primeira chamada pode demorar porque o Portal SUS publica um arquivo anual completo; trocar apenas o município no mesmo ano deve reutilizar o artefato.

4. Pesquisar hospitais

Liste os 10 maiores hospitais de Manaus por número de leitos existentes.

O cliente pode usar cnes_search_municipio com tipo_estabelecimento="HOSPITAL", order_by="leitos_existentes" e limit=10.

Nesse ponto, a instalação está funcional: o servidor foi iniciado, uma competência foi carregada e uma consulta retornou estabelecimentos reais.

Usar o contrato v2

Para razão social, CNPJ, mantenedora, endereço, contato institucional, geolocalização qualificada, habilitações e leitos por tipo, carregue a base mensal completa:

Carregue a competência 202512 usando a fonte datasus_base_completa.

Uma consulta v2 simples já pode usar esse lote. Gatilhos e score, porém, precisam de um lote v2 retido para cada competência comparada. Antes dos exemplos de tendência, solicite também:

Carregue a competência 202012 usando a fonte datasus_base_completa.

Se houver mais de um lote v2 para a mesma competência, informe explicitamente lote_a e lote_b. Depois, use prompts como:

• “Mostre hospitais com UTI em São Paulo usando o contrato v2.”

• “Agrupe as unidades por CNPJ da mantenedora e ordene pelo total de leitos.”

• “Compare 202012 e 202512 e mostre expansões de pelo menos 20 leitos.”

• “Calcule o score dos leads usando pesos iguais para porte, complexidade, mix pagador e tendência.”

O ZIP mensal completo pode conter centenas de milhares de estabelecimentos e leva mais tempo e espaço que a fonte anual de hospitais e leitos.

Fontes e contratos

O contrato v1 mantém os 11 campos canônicos originais. O contrato aditivo v2 preserva v1 e acrescenta dados institucionais, geolocalização qualificada, habilitações e leitos desagregados.

Leia docs/fontes.md para conhecer layouts, regras de derivação, cache, limites e fontes investigadas.

Ferramentas disponíveis

As 23 ferramentas são agrupadas por objetivo:

As 19 ferramentas existentes permanecem compatíveis com o contrato v1. As quatro ferramentas comerciais usam v2; cnes_export mantém v1 por padrão e também suporta o perfil CRM baseado em v2.

Inputs e outputs possuem JSON Schema. Parâmetros extras são rejeitados, CNES exige sete dígitos, UF exige duas letras e limit aceita valores de 1 a 500. Falhas recuperáveis são retornadas ao cliente como erro MCP, não como sucesso vazio. Referências de arquivos em respostas são relativas aos diretórios configurados; o servidor não divulga caminhos absolutos do host.

Exportar para CRM

cnes_export aceita CSV, JSON, JSONL e XLSX. Para exportar exatamente uma seleção, informe cnes_list; para repetir uma consulta paginada, use os mesmos filtros, limit, offset e order_by.

Exemplo de solicitação:

Exporte estes 10 códigos CNES em JSONL com perfil crm_generico.

O perfil crm_generico usa cnes:cnpj como chave de deduplicação. CSV, JSON e JSONL recebem proveniência por registro; XLSX recebe a aba _metadados. Os metadados incluem competência, lote, filtros, versão da fonte, timestamp e versão do contrato.

Dados locais, cache e retenção

• Um lote fica ativo por vez, mas lotes anteriores podem ser consultados pelo identificador.

• A fonte anual reutiliza o download entre filtros do mesmo ano e revalida períodos ainda abertos.

• A base completa mantém Parquets imutáveis por lote e consulta os dados com DuckDB.

• cnes_purge fica desabilitado por padrão. O operador precisa iniciar o servidor com MCP_CNES_ALLOW_PURGE=true e cada chamada deve informar confirmacao como EXCLUIR_LOTE:<lote_id> ou LIMPAR_CACHE.

• Não apague manualmente um banco ou Parquet enquanto o servidor estiver em uso.

Consulte docs/data-retention.md para a política mínima de dados e retenção.

Privacidade e limites de interpretação

• O pipeline padrão aceita somente estabelecimentos classificados como pessoa jurídica na base completa.

• CPF e nomes de responsáveis, profissionais ou diretores não são coletados, persistidos ou exportados.

• Telefone, e-mail, CNPJ e endereço são tratados como dados institucionais.

• No contrato v2, campos numéricos marcados como ausentes permanecem nulos e aparecem em campos_ausentes; o contrato v1 preserva sua semântica histórica.

• leitos_sus / leitos_existentes representa mix cadastral de leitos, não taxa de ocupação.

• Resultados dependem da atualização e disponibilidade das fontes oficiais.

Desenvolvimento e verificação

Suíte local

# Testes determinísticos; não acessam serviços externos
uv run pytest -m "not live"

# Qualidade estática
uv run ruff check src tests benchmarks
uv run pyright

# Cobertura
uv run pytest tests/unit tests/integration -m "not live" `
  --cov=mcp_cnes.domain --cov=mcp_cnes.application `
  --cov-report=term-missing

# Contratos do SDK MCP
uv run pytest tests/unit/test_mcp_sdk_contract.py -m "not live"

# Artefatos de distribuição
uv build

Em macOS ou Linux, substitua o acento grave de continuação do PowerShell por \ ou execute o comando de cobertura em uma única linha.

MCP Inspector

uv run mcp dev src/mcp_cnes/mcp_app.py

Testes externos

Os testes live só acessam a internet quando explicitamente autorizados:

$env:CNES_RUN_LIVE_TESTS = "1"
uv run pytest -m live
Remove-Item Env:CNES_RUN_LIVE_TESTS

O workflow Live smoke pode ser iniciado manualmente no GitHub Actions. O CI de pull requests executa auditoria de dependências, Ruff, Pyright, testes de unidade, integração, contratos e cobertura.

Solução de problemas

uv não é reconhecido

Abra um novo terminal após a instalação. Use where.exe uv no Windows ou command -v uv em macOS/Linux. Se necessário, coloque o caminho absoluto no campo command da configuração MCP.

O cliente não mostra as ferramentas

1. Execute uv run mcp-cnes no diretório do projeto.

2. Confirme que o processo permanece aguardando em stdio.

3. Valide o JSON do cliente e o caminho absoluto em --directory.

4. Reinicie completamente o cliente MCP.

5. Confira os logs do cliente, não apenas a janela de conversa.

uv sync --locked falha

Confirme uv --version e acesso ao índice de pacotes. A .venv é descartável, mas remova somente a .venv deste checkout e apenas quando nenhum processo do MCP estiver usando seus executáveis.

Uma fonte está indisponível

Use cnes_list_sources para obter o status e o motivo. Portal SUS e DATASUS são serviços externos; tente novamente apenas quando a falha for marcada como transitória. O servidor não substitui indisponibilidade por lista vazia.

A importação manual foi rejeitada

Confirme que o arquivo é CSV, está dentro de MCP_CNES_DATA_DIR, respeita MCP_CNES_MAX_CSV_SIZE_BYTES e, quando configurada, consta em MCP_CNES_ALLOWED_CSV_FILES.

O banco parece bloqueado ou inconsistente

Não apague o catálogo em uso. Encerre os clientes que executam o MCP e preserve os arquivos para diagnóstico. Use um diretório separado para smokes e validações de cutover.

Documentação adicional

Estrutura do projeto

mcp-cnes/
├── pyproject.toml
├── uv.lock
├── src/mcp_cnes/
│   ├── domain/              # modelos e regras puras
│   ├── application/         # casos de uso e portas
│   ├── infrastructure/      # fontes, importação, persistência e exports
│   ├── interfaces/mcp/      # servidor, tools e schemas MCP
│   ├── mcp_app.py           # objeto usado pelo MCP CLI e Inspector
│   └── __main__.py          # entrypoint stdio
├── tests/                   # testes unitários, integração e contratos
├── docs/                    # fontes, retenção, cutover e releases
└── downloads/               # dados locais; ignorados pelo Git

Licença e origem dos dados

O código é distribuído sob a licença MIT.

Os dados do CNES são públicos e disponibilizados pelo Ministério da Saúde/DATASUS. A licença do código não altera os termos, a disponibilidade nem a responsabilidade sobre os dados de origem.