terminologia

Name: terminologia
Author: voa.health

Local

docs.voa.healthHealth0Updated today

Repository Visit website

About terminologia

terminologia is a Python client and MCP server for querying healthcare terminology systems served by Voa, including Brazilian and international code sets. Healthcare software teams can search, look up, validate, and translate codes against the published online service.

Key features

01Search terminology concepts
02Look up and validate codes
03Translate codes between systems
04CLI with JSON output
05Local MCP server mode

Use cases

01Search ICD-10 or TUSS concepts
02Validate a healthcare code
03Translate a code to another system

MCP support

The Python package can start a local MCP server with `terminologia mcp`. It exposes access to the online terminology service to connected agents.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "health-voa-terminologia": {
      "command": "uvx",
      "args": [
        "terminologia"
      ],
      "env": {
        "TERMINOLOGIA_KEY": "<TERMINOLOGIA_KEY>",
        "TERMINOLOGIA_URL": "<TERMINOLOGIA_URL>"
      }
    }
  }
}

Run commanduvx terminologia

Environment variables to set

TERMINOLOGIA_KEYSecretChave de produto da organização (sk_voa_) com escopo terminology:read.

TERMINOLOGIA_URLURL base FHIR; substitui o endpoint padrão.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

pypiterminologia0.1.1stdio

Tools

Saved tool list · updated 1d ago

Parameter	Type	Required	Description
n	integer	No
texto	string	Yes
sistema	enum	Yes	cid10 \| ciap2 \| tuss \| tuss-diarias \| tuss-materiais \| tuss-medicamentos \| sigtap \| sigtap-grupo \| sigtap-sub-grupo \| sigtap-servico \| sigtap-registro \| sigtap-financiamento \| sigtap-modalidade \| anvisa \| cbo \| cfm-especialidade \| rol-ans \| dut \| cnes \| ans-operadora \| loinc \| ucum \| tiss-23 \| tiss-25 \| tiss-26 \| tiss-27 \| tiss-28 \| tiss-29 \| tiss-30 \| tiss-31 \| tiss-32 \| tiss-33 \| tiss-34 \| tiss-35 \| tiss-36 \| tiss-37 \| tiss-38 \| tiss-39 \| tiss-40 \| tiss-41 \| tiss-42 \| tiss-43 \| tiss-44 \| tiss-45 \| tiss-46 \| tiss-47 \| tiss-48 \| tiss-49 \| tiss-50 \| tiss-51 \| tiss-52 \| tiss-53 \| tiss-54 \| tiss-55 \| tiss-56 \| tiss-57 \| tiss-58 \| tiss-59 \| tiss-60 \| tiss-61 \| tiss-62 \| tiss-63 \| tiss-65 \| tiss-66 \| tiss-67 \| tiss-68 \| tiss-69 \| tiss-70 \| tiss-71 \| tiss-72 \| tiss-73 \| tiss-74 \| tiss-75 \| tiss-76 \| tiss-77 \| tiss-78 \| tiss-79 \| tiss-80 \| tiss-81 \| tiss-82 \| tiss-87 \| voa-categoria

Details

From the project README

Documentação · tiss

terminologia

Cliente Python e ferramentas MCP para consultar CID-10, CIAP-2, TUSS, TISS, SIGTAP, CNES, ANVISA, CBO, LOINC, UCUM e outros sistemas de terminologia em FHIR.

Início rápido

pip install terminologia

Crie uma chave de produto da organização em https://tiss-api.voa.health/org e configure:

export TERMINOLOGIA_KEY=sk_voa_...

Chaves sk_tiss_ existentes também podem ser usadas quando possuem o escopo terminology:read.

O endpoint padrão é https://terminologia.voa.health/api/v1/fhir. O argumento base_url do cliente tem precedência; sem ele, defina TERMINOLOGIA_URL para usar outro endpoint.

import terminologia

resultado = terminologia.cid10.buscar("dor torácica")
for conceito in resultado:
    print(conceito.coding())

consulta = terminologia.tuss.lookup("10101012")
if consulta:
    print(consulta.display)

for estabelecimento in terminologia.sistema("cnes").buscar("hospital das clínicas", n=5):
    print(estabelecimento.code, estabelecimento.display)

CLI

Comando	Uso
`terminologia buscar <sistema> <texto> [-n N]`	Buscar conceitos
`terminologia lookup <sistema> <código>`	Consultar um código
`terminologia validar <sistema> <código>`	Validar um código
`terminologia traduzir <sistema> <código> --para SISTEMA`	Traduzir um código
`terminologia sistemas`	Listar os sistemas
`terminologia mcp`	Iniciar o servidor MCP local

Use --json nos comandos, exceto mcp, para receber JSON. O código de saída é 0 para sucesso, 1 quando não há resultado ou o código é inválido e 2 para erros de uso, chave, acesso, cota, rede ou servidor.

Conectar agentes

Claude Code:

claude mcp add terminologia -e TERMINOLOGIA_KEY=sk_voa_... -- \
  uvx --from "terminologia[mcp]" terminologia mcp

Codex (~/.codex/config.toml):

[mcp_servers.terminologia]
command = "uvx"
args = ["--from", "terminologia[mcp]", "terminologia", "mcp"]

[mcp_servers.terminologia.env]
TERMINOLOGIA_KEY = "sk_voa_..."

Cursor (mcp.json):

{
  "mcpServers": {
    "terminologia": {
      "command": "uvx",
      "args": ["--from", "terminologia[mcp]", "terminologia", "mcp"],
      "env": {
        "TERMINOLOGIA_KEY": "sk_voa_..."
      }
    }
  }
}

Sistemas

Nome	Canônico
`cid10`	`http://hl7.org/fhir/sid/icd-10`
`ciap2`	`http://hl7.org/fhir/sid/icpc-2`
`tuss`	`https://voa.health/fhir/CodeSystem/tuss`
`tuss-diarias`	`https://voa.health/fhir/CodeSystem/tuss-diarias-taxas-gases-medicinais`
`tuss-materiais`	`https://voa.health/fhir/CodeSystem/tuss-materiais-opme`
`tuss-medicamentos`	`https://voa.health/fhir/CodeSystem/tuss-medicamentos`
`sigtap`	`https://voa.health/fhir/CodeSystem/sigtap`
`sigtap-grupo`	`https://voa.health/fhir/CodeSystem/sigtap-grupo`
`sigtap-sub-grupo`	`https://voa.health/fhir/CodeSystem/sigtap-sub-grupo`
`sigtap-servico`	`https://voa.health/fhir/CodeSystem/sigtap-servico`
`sigtap-registro`	`https://voa.health/fhir/CodeSystem/sigtap-registro`
`sigtap-financiamento`	`https://voa.health/fhir/CodeSystem/sigtap-financiamento`
`sigtap-modalidade`	`https://voa.health/fhir/CodeSystem/sigtap-modalidade`
`anvisa`	`urn:voa:anvisa:registro`
`cbo`	`https://voa.health/fhir/CodeSystem/cbo`
`cfm-especialidade`	`https://voa.health/fhir/CodeSystem/cfm-especialidade`
`rol-ans`	`https://voa.health/fhir/CodeSystem/rol-ans`
`dut`	`https://voa.health/fhir/CodeSystem/rol-diretrizes-dut`
`cnes`	`urn:voa:br:cnes`
`ans-operadora`	`urn:voa:br:ans-registro`
`loinc`	`http://loinc.org`
`ucum`	`http://unitsofmeasure.org`
`voa-categoria`	`https://voa.health/fhir/CodeSystem/voa-categoria-servico`

Tabelas de domínio TISS (59)

Também acessíveis por terminologia.tiss_dominio(<número>).

Nome	Canônico
`tiss-23`	`https://voa.health/fhir/CodeSystem/tiss-carater-atendimento`
`tiss-25`	`https://voa.health/fhir/CodeSystem/tiss-codigo-despesa`
`tiss-26`	`https://voa.health/fhir/CodeSystem/tiss-conselho-profissional`
`tiss-27`	`https://voa.health/fhir/CodeSystem/tiss-debitos-creditos`
`tiss-28`	`https://voa.health/fhir/CodeSystem/tiss-dentes`
`tiss-29`	`https://voa.health/fhir/CodeSystem/tiss-diagnostico-imagem`
`tiss-30`	`https://voa.health/fhir/CodeSystem/tiss-escala-capacidade-funcional`
`tiss-31`	`https://voa.health/fhir/CodeSystem/tiss-estadiamento-tumor`
`tiss-32`	`https://voa.health/fhir/CodeSystem/tiss-faces-dente`
`tiss-33`	`https://voa.health/fhir/CodeSystem/tiss-finalidade-tratamento`
`tiss-34`	`https://voa.health/fhir/CodeSystem/tiss-forma-pagamento`
`tiss-35`	`https://voa.health/fhir/CodeSystem/tiss-grau-participacao`
`tiss-36`	`https://voa.health/fhir/CodeSystem/tiss-indicador-acidente`
`tiss-37`	`https://voa.health/fhir/CodeSystem/tiss-indicador-debito-credito`
`tiss-38`	`https://voa.health/fhir/CodeSystem/tiss-mensagens`
`tiss-39`	`https://voa.health/fhir/CodeSystem/tiss-motivo-encerramento`
`tiss-40`	`https://voa.health/fhir/CodeSystem/tiss-origem-guia`
`tiss-41`	`https://voa.health/fhir/CodeSystem/tiss-regime-internacao`
`tiss-42`	`https://voa.health/fhir/CodeSystem/tiss-regioes-boca`
`tiss-43`	`https://voa.health/fhir/CodeSystem/tiss-sexo`
`tiss-44`	`https://voa.health/fhir/CodeSystem/tiss-situacao-inicial-dente`
`tiss-45`	`https://voa.health/fhir/CodeSystem/tiss-status-solicitacao`
`tiss-46`	`https://voa.health/fhir/CodeSystem/tiss-status-cancelamento`
`tiss-47`	`https://voa.health/fhir/CodeSystem/tiss-status-protocolo`
`tiss-48`	`https://voa.health/fhir/CodeSystem/tiss-tecnica-utilizada`
`tiss-49`	`https://voa.health/fhir/CodeSystem/tiss-tipo-acomodacao`
`tiss-50`	`https://voa.health/fhir/CodeSystem/tiss-tipo-atendimento`
`tiss-51`	`https://voa.health/fhir/CodeSystem/tiss-tipo-atendimento-odontologia`
`tiss-52`	`https://voa.health/fhir/CodeSystem/tiss-tipo-consulta`
`tiss-53`	`https://voa.health/fhir/CodeSystem/tiss-tipo-demonstrativo`
`tiss-54`	`https://voa.health/fhir/CodeSystem/tiss-tipo-guia`
`tiss-55`	`https://voa.health/fhir/CodeSystem/tiss-tipo-faturamento`
`tiss-56`	`https://voa.health/fhir/CodeSystem/tiss-natureza-guia`
`tiss-57`	`https://voa.health/fhir/CodeSystem/tiss-tipo-internacao`
`tiss-58`	`https://voa.health/fhir/CodeSystem/tiss-tipo-quimioterapia`
`tiss-59`	`https://voa.health/fhir/CodeSystem/tiss-unidade-federacao`
`tiss-60`	`https://voa.health/fhir/CodeSystem/tiss-unidade-medida`
`tiss-61`	`https://voa.health/fhir/CodeSystem/tiss-via-acesso`
`tiss-62`	`https://voa.health/fhir/CodeSystem/tiss-via-administracao`
`tiss-63`	`https://voa.health/fhir/CodeSystem/tiss-grupos-procedimentos-ans`
`tiss-65`	`https://voa.health/fhir/CodeSystem/tiss-metastases`
`tiss-66`	`https://voa.health/fhir/CodeSystem/tiss-nodulo`
`tiss-67`	`https://voa.health/fhir/CodeSystem/tiss-tumor`
`tiss-68`	`https://voa.health/fhir/CodeSystem/tiss-categoria-despesa`
`tiss-69`	`https://voa.health/fhir/CodeSystem/tiss-versao-componente-comunicacao`
`tiss-70`	`https://voa.health/fhir/CodeSystem/tiss-forma-envio`
`tiss-71`	`https://voa.health/fhir/CodeSystem/tiss-tipo-atendimento-operadora-intermediaria`
`tiss-72`	`https://voa.health/fhir/CodeSystem/tiss-tipo-identificacao-beneficiario`
`tiss-73`	`https://voa.health/fhir/CodeSystem/tiss-etapas-autorizacao`
`tiss-74`	`https://voa.health/fhir/CodeSystem/tiss-motivos-ausencia-codigo-validacao`
`tiss-75`	`https://voa.health/fhir/CodeSystem/tiss-cobertura-especial`
`tiss-76`	`https://voa.health/fhir/CodeSystem/tiss-regime-atendimento`
`tiss-77`	`https://voa.health/fhir/CodeSystem/tiss-saude-ocupacional`
`tiss-78`	`https://voa.health/fhir/CodeSystem/tiss-tipo-pagamento`
`tiss-79`	`https://voa.health/fhir/CodeSystem/tiss-modelos-remuneracao`
`tiss-80`	`https://voa.health/fhir/CodeSystem/tiss-formato-documento`
`tiss-81`	`https://voa.health/fhir/CodeSystem/tiss-tipo-documento`
`tiss-82`	`https://voa.health/fhir/CodeSystem/tiss-centro-consumo`
`tiss-87`	`https://voa.health/fhir/CodeSystem/tiss-terminologias-unificadas`

A allowlist de licença é definida pelo servidor.

Atribuição

This material contains content from LOINC® (http://loinc.org). LOINC is copyright © Regenstrief Institute, Inc. and the LOINC Committee and is available at no cost under the license at http://loinc.org/license.

Erros

Exceção	Significado
`ChaveInvalidaError`	Chave ausente ou inválida
`AcessoNegadoError`	A chave não tem acesso ao sistema
`CotaExcedidaError`	Cota excedida; consulte `retry_after`
`RedeError`	Falha de conexão
`TempoEsgotadoError`	Tempo limite excedido
`ServidorError`	Erro retornado pelo serviço

terminologia ou tiss.tuss?

tiss.tuss consulta a tabela TUSS offline embutida no pacote tiss. terminologia é o cliente online da terminologia servida pela Voa, cobre todos os sistemas e valida na versão publicada. Requer chave e está sujeito à cota da organização.

Licença

Apache-2.0. Consulte LICENSE.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.

terminologia

About terminologia

Key features

Use cases

MCP support

Configuration

Tools

Details

terminologia

Início rápido

CLI

Conectar agentes

Sistemas

Atribuição

Erros

terminologia ou tiss.tuss?

Licença

Comments

New to MCP?

What is MCP (Model Context Protocol)?

How do MCP servers differ from clients?

Should I use a local or a remote server?

How do I install a server in Claude, Cursor and others?

Are listed projects reviewed? What does “Verified” mean?

My project is listed. How do I claim it?