contai-mcp 0.1.0

MCP server Python para 26 calculadoras fiscais brasileiras (CLT, PJ, impostos, finanças, saúde) — HTTP client da API Contaí. Use com Claude Desktop, Cursor, Cline.

contai-mcp

MCP server Python para 26 calculadoras fiscais brasileiras.

CLT, PJ, impostos, finanças, saúde — usando Model Context Protocol. Funciona dentro de Claude Desktop, Cursor, Cline, Continue, ou qualquer cliente MCP que fale stdio.

Não rola engine local: é um HTTP client da API Contaí, que executa o engine TypeScript versionado, mesma fórmula que roda em calculas.com.br.

---

Por que Python?

A versão TypeScript (@contai-evoluke/mcp-server) é a primária. Esta versão Python existe pra:

• ML/data engineers que já têm Python configurado e não querem instalar Node
• Usuários de Cursor/Cline com setup Python pré-existente
• Pipelines automatizados onde Python é o ambiente nativo

Instalação

Recomendado — via uvx (sem install)

uvx contai-mcp

Funciona em Claude Desktop direto:

{
  "mcpServers": {
    "contai": {
      "command": "uvx",
      "args": ["contai-mcp"]
    }
  }
}

Via pip

pip install contai-mcp
contai-mcp

Configuração

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "contai": {
      "command": "uvx",
      "args": ["contai-mcp"]
    }
  }
}

Reinicie o Claude Desktop. As tools calcular_rescisao_clt, calcular_salario_liquido, etc., aparecem.

Cursor

Settings → Cursor Settings → MCP → Add new MCP server:

• Name: contai
• Command: uvx contai-mcp

Cline / Continue / outros

Aponte qualquer cliente MCP que suporte stdio transport para:

uvx contai-mcp

Variáveis de ambiente (opcional)

# API key (Pro/Team — sem ela usa free tier 100/dia por IP)
export CONTAI_API_KEY="ck_live_..."

# Override base URL (default https://api.calculas.com.br)
export CONTAI_API_URL="http://localhost:8787"

# Timeout em ms (default 5000)
export CONTAI_TIMEOUT_MS=10000

Tools disponíveis (26)

Nota: a API REST tem 27 calcs no total, mas porcentagem (a×b/100) é trivial demais para justificar uma tool MCP — LLMs lidam com isso direto. Os 5 lookup tools (consultar_inss_vigente, etc.) só existem na versão TS via stdio. Roadmap futuro pode adicionar GETs REST equivalentes.

Trabalhistas (12)

calcular_rescisao_clt, calcular_salario_liquido, calcular_13o_salario, calcular_ferias, calcular_horas_extras, calcular_horas_extras_dsr, calcular_fgts_acumulado, calcular_adicional_noturno, calcular_aviso_previo, calcular_inss_facultativo, calcular_insalubridade_periculosidade, calcular_seguro_desemprego

PJ (4)

calcular_mei_das, calcular_simples_nacional, calcular_lucro_presumido, calcular_comparador_regime_tributario

Imóveis (2)

calcular_financiamento_imobiliario, calcular_itbi

Impostos (2)

calcular_itcmd, calcular_irpf_restituicao

Veículos (1)

calcular_ipva

Finanças (3)

calcular_juros_compostos, calcular_simulador_aposentadoria, calcular_consorcio_vs_financiamento

Saúde (2)

calcular_imc, calcular_calculadora_gestacional

Como funciona

Claude Desktop                contai-mcp (Python)            api.calculas.com.br
     │                              │                                │
     │── tools/list ────────────────▶                                │
     │◀── 27 tools listadas ────────│                                │
     │                              │                                │
     │── call_tool(rescisao_clt) ──▶│                                │
     │                              │── POST /v1/calc/rescisao-clt ▶│
     │                              │◀── { totalLiquidoCents: ... } │
     │◀── resultado JSON ──────────│                                │

Sem rede em runtime do LLM = não há latência extra além do HTTP da API. Cache CDN da API absorve a maioria dos hits idempotentes.

Verificar funcionamento

No Claude Desktop, pergunte:

"Calcule a rescisão CLT pra alguém com salário R$ 5.000 admitido em 01/01/2024 e demitido sem justa causa em 01/04/2026"

Deve invocar calcular_rescisao_clt automaticamente.

Erros estruturados

Em vez de raise, retorna envelope:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "salarioBrutoCents: must be positive",
    "details": { "path": ["salarioBrutoCents"] }
  }
}

Codes: INVALID_INPUT, UNKNOWN_CALC, RATE_NOT_AVAILABLE, SCHEMA_DRIFT, INTERNAL, TIMEOUT, NETWORK, RATE_LIMITED, INVALID_KEY.

Rate limits

Tier	Limite	Auth
Free	100 req/dia (IP-based)	sem CONTAI_API_KEY
Pro	10.000 req/dia	ck_live_...
Team	50.000 req/dia	ck_live_...

Detalhes em docs.calculas.com.br/rate-limits.

Desenvolvimento

cd packages/mcp-server-python
uv sync                       # cria venv + instala deps
uv run pytest                 # roda tests
uv run ruff check src tests   # lint
uv run python scripts/sync-tools.py  # valida sync com OpenAPI da API

Licença

MIT