Hacienda Costa Rica

🇨🇷 mcp-hacienda-cr

Servidor MCP que conecta a Claude, Cursor y otros asistentes de IA con los datos públicos del Ministerio de Hacienda de Costa Rica: tipo de cambio, situación tributaria de contribuyentes, códigos CABYS con su IVA y exoneraciones. Pensado para la facturación electrónica.

English summary · Herramientas · Instalación · Cómo funciona

Grabado con MCP Inspector contra la API real de Hacienda: tipo de cambio de hoy, códigos CABYS de "café tostado" con su IVA y la situación tributaria de la CNFL.

💬 Qué puedes preguntarle a tu asistente

"¿Qué código CABYS uso para vender café tostado y cuánto IVA lleva?"

Hay 71 códigos para café tostado. Por ejemplo, 2391102010100 (café tostado sin descafeinar, en grano) paga IVA 1%, pero 2391102020000 (café tostado descafeinado) paga IVA 13%.

"Antes de facturarle, ¿la empresa 3-101-000046 está al día con Hacienda?"

COMPAÑIA NACIONAL DE FUERZA Y LUZ S.A. · Cédula jurídica · Inscrita en el régimen general · al día (no morosa ni omisa) · Actividad principal: 3510.0, generación, transmisión y distribución de energía eléctrica.

"¿A cuánto está el dólar hoy?" · "¿La exoneración AL-00020402-24 sigue vigente?"

Son respuestas reales del servidor contra la API de Hacienda.

🧰 Herramientas

Todas son de solo lectura (readOnlyHint) y usan APIs públicas de Hacienda: no necesitan registro, token ni API key.

📦 Instalación

Requiere Node.js 18 o superior.

Claude Desktop

En claude_desktop_config.json (Configuración → Desarrollador → Editar configuración):

{
  "mcpServers": {
    "hacienda-cr": {
      "command": "npx",
      "args": ["-y", "mcp-hacienda-cr"]
    }
  }
}

Claude Code

claude mcp add hacienda-cr -- npx -y mcp-hacienda-cr

Cursor, VS Code y otros clientes MCP

Usa el comando npx -y mcp-hacienda-cr con transporte stdio.

⚙️ Cómo funciona

flowchart LR
    U["Tú"] --> A["Asistente de IA<br/>(Claude, Cursor…)"]
    A -- "MCP (stdio)" --> S["mcp-hacienda-cr"]
    S -- "HTTPS" --> H["api.hacienda.go.cr"]

• TypeScript con el SDK oficial de MCP; cada herramienta valida su entrada con Zod.
• Respuestas dobles: texto legible para la conversación y structuredContent para que el modelo trabaje con datos exactos.
• Errores pensados para el usuario: una cédula con formato inválido, un código inexistente o la API de Hacienda caída se responden con un mensaje claro, no con una excepción.
• Caché en memoria: 10 minutos para el tipo de cambio y 1 hora para el resto, para no saturar la API de Hacienda.
• Validación local antes de llamar a la API: cédula física (9 dígitos), jurídica o NITE (10) y DIMEX (11–12); código CABYS de 13 dígitos.

Calidad

npm install
npm test            # unitarios (sin red)
npm run test:live   # contrato con la API real de Hacienda
npm run smoke       # servidor compilado por stdio, de punta a punta

⚠️ Aviso

Los datos provienen de las APIs públicas del Ministerio de Hacienda y son de referencia. Este proyecto no está afiliado al Ministerio de Hacienda. Confirma las decisiones fiscales con un contador o directamente con Hacienda.

🇺🇸 English summary

mcp-hacienda-cr is a Model Context Protocol server that lets AI assistants (Claude, Cursor, …) query Costa Rica's Ministry of Finance public APIs: official exchange rates, taxpayer status (registered, delinquent or non-filer, economic activities), CABYS product/service codes with their VAT rate, and tax exemptions. It targets e-invoicing, where every invoice line needs a CABYS code and the right VAT rate.

No API keys needed. TypeScript + the official MCP SDK, Zod-validated inputs, text plus structured output, friendly errors, in-memory caching, 25 unit tests, live contract tests, a stdio smoke test, and CI on Node 18/20/22 with a weekly live run.

claude mcp add hacienda-cr -- npx -y mcp-hacienda-cr

Ney Fred Jiménez Campos · LinkedIn · GitHub · MIT License