ans-mcp

O problema

Por que este projeto existe

Como funciona

Do FTP da agência ao agente, em quatro camadas

1. 01 →

   Download

   Baixa os cinco conjuntos do FTP de dados abertos da ANS, incluindo o zip da TUSS. Uma fonte fora do ar não impede as outras, mas formato inesperado interrompe o sync de propósito.

2. 02 →

   Parser que trava no cabeçalho

   Cada parser confere as colunas que espera e aceita só os nomes já conferidos na origem. Um formato novo levanta erro em vez de adivinhar: parser lendo a coluna errada devolve número plausível, que é pior que não devolver nada.

3. 03 →

   DuckDB em formato longo

   IDSS, garantia e glosas viram tabelas longas. O IDSS vem largo da ANS, com uma coluna por indicador e par de anos, e os nomes dos indicadores já mudaram duas vezes: longo sobrevive à próxima troca sem migração.

4. 04

   Troca atômica da base

   O sync constrói a base nova ao lado e troca as duas por rename no fim. Quem está consultando não é interrompido, e a cópia sai compactada: sem isso o arquivo passava de 120 MB sem ganhar uma linha.

O que ele lê

Sete tabelas de dados abertos

Contagens lidas da base real em 12/10/2026. Cada uma saiu de um count(*), não de estimativa. A base inteira ocupa 62 MB em disco.

• Terminologia TUSS 67.884 termos 18 tabelas de domínio, das 19 do zip. Procedimentos, medicamentos, materiais e OPME, diárias e as tabelas de domínio menores.
• Operadoras ativas 1.106 operadoras Cadastro com registro na ANS, CNPJ, razão social, nome fantasia, modalidade e município. Só as ativas.
• Operadoras canceladas 3.078 operadoras Com data e motivo do cancelamento.
• Histórico do IDSS 43.724 notas Formato longo, uma linha por operadora, indicador e ano. Anos-base de 2015 a 2024.
• Garantia de atendimento 33.025 posições 35 competências trimestrais, com a faixa como a ANS publica.
• Painel de glosas 48.184 valores Quatro indicadores em formato longo: tempo médio de pagamento, glosa inicial, glosa final e guias sem retorno.
• Regimes especiais 118 resoluções Resoluções de direção técnica, de 77 operadoras.

As ferramentas

Três tools MCP, nenhuma com LLM

O modelo chama estas funções durante a conversa. Toda resposta traz total, retornados e truncado: conte pelo total, nunca pelo tamanho da lista. Os retornos abaixo são saídas reais de 11/10/2026, com as listas longas cortadas, e não foram regravados em 12/10/2026.

consultar_tuss(
    termo_ou_codigo: str,
    apenas_vigentes: bool = True,
    limite: int = 20,   # 1 a 200
)

{
  "termo_consultado": "stent coronário",
  "total": 4311,
  "retornados": 2,
  "truncado": true,
  "resultados": [
    {
      "cd_termo": "71220577",
      "tabela": "tabela_19_materiais_e_opme",
      "nm_termo": "STENT CORONÁRIO CHROMA",
      "ds_termo": null,
      "dt_inicio_vigencia": "2016-10-01",
      "dt_fim_vigencia": null,
      "dt_fim_implantacao": "2016-12-31",
      "registro_anvisa": "80102511360",
      "fabricante": "VR MEDICAL IMPORTADORA E DISTRIBUIDORA DE PRODUTOS MÉDICOS LTDA",
      "classe_risco": "IV",
      "nome_tecnico": "STENT PARA ARTÉRIAS CORONÁRIAS"
    }
  ],
  "aviso": "Terminologia Unificada da Saúde Suplementar, dos dados abertos da ANS. O código e a vigência valem para troca de informações no padrão TISS, e não dizem se o procedimento tem cobertura obrigatória: isso é o Rol de Procedimentos, que é outra norma. Casaram 4311 termos e estão aqui os 2 primeiros..."
}

consultar_operadora(
    nome_registro_ou_cnpj: str,
    limite: int = 10,   # 1 a 50
)

{
  "termo_consultado": "417548",
  "total": 1,
  "retornados": 1,
  "truncado": false,
  "resultados": [
    {
      "registro_operadora": "417548",
      "cnpj": "03033006000153",
      "razao_social": "CAIXA DE ASSISTÊNCIA OSWALDO CRUZ",
      "nome_fantasia": "FIOSAÚDE",
      "modalidade": "Autogestão",
      "uf": "RJ",
      "cidade": "Rio de Janeiro",
      "data_registro_ans": "2010-09-21",
      "visto_na_ultima_coleta": true,
      "idss": [
        { "indicador": "IDSS", "ano_divulgacao": 2025, "ano_base": 2024, "nota": 0.7232 },
        { "indicador": "IDQS", "ano_divulgacao": 2025, "ano_base": 2024, "nota": 0.8918 }
      ],
      "garantia_atendimento": [
        { "competencia": "4º Trim./2024", "dt_inicio": "2024-10-01", "dt_fim": "2024-12-31", "posicao": "FAIXA 3" }
      ],
      "glosas": [
        { "indicador": "tempo_medio_pagamento", "periodo": "2025-02", "valor": 10.68, "porte": "Pequeno" },
        { "indicador": "percentual_glosa_final", "periodo": "2025-02", "valor": 3.37, "porte": "Pequeno" }
      ]
    }
  ],
  "aviso": "Dados abertos da ANS, cruzados pelo registro da operadora. Cada bloco vem de um conjunto diferente, com periodicidade própria..."
}

Onde ele falha

O que as tools não dizem

Cada item abaixo foi conferido baixando o arquivo ou consultando a base, não deduzido de documentação. São as coisas que fazem alguém tirar a conclusão errada de uma resposta certa.

Como rodar

Local, por stdio, sem serviço hospedado

Não há conector hospedado nem versão remota deste servidor. Ele roda na sua máquina e fala stdio com o cliente MCP. Precisa de Python 3.12+, uv e cerca de 62 MB de disco para a base (tamanho lido em 12/10/2026).

# 1. na pasta do projeto: instalar e configurar
uv sync
cp .env.example .env

# 2. montar a base (baixa ~25 MB da ANS, cerca de 2 min)
uv run ans-cli sync --publicar

# 3. conferir quantas linhas entraram em cada tabela
uv run ans-cli estado

# 4. registrar o servidor MCP (stdio) no Claude Code
claude mcp add --scope user ans -- uv --directory /caminho/do/ans-mcp run ans-mcp

Manutenção e consulta direta

Para manter a base atualizada sem sessão aberta há um timer systemd no projeto, que roda a coleta com --publicar todo dia de madrugada, com atraso aleatório. O atraso importa: horário fixo resolveria a concorrência numa máquina só, mas faria todas as instalações baterem no servidor da ANS no mesmo minuto.

# uma fonte só, quando a ANS republica apenas aquela
uv run ans-cli sync --fonte tuss

# consultar da linha de comando, sem cliente MCP
uv run ans-cli tuss "stent coronário"
uv run ans-cli operadora 417548