mcp-hacienda-cr
The server exposes read-only tools for querying Costa Rica’s Ministry of Finance public data.
Get today’s reference exchange rate for USD and EUR.
Look up a taxpayer’s status, regime, and economic activities by identification number.
Search CABYS product/service codes by description, including VAT rates.
Get details for a specific 13-digit CABYS code.
Look up a tax exemption by authorization number, including beneficiary, percentage, validity, and covered CABYS codes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-hacienda-cr Busca el código CABYS para café tostado y dime cuánto IVA lleva"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-hacienda-cr
Un servidor MCP que le da a Claude, Cursor y otros asistentes de IA acceso a los datos públicos del Ministerio de Hacienda de Costa Rica: el tipo de cambio, la situación tributaria de un contribuyente, los códigos CABYS con su tarifa de IVA y las exoneraciones. Además valida el XML de una factura electrónica 4.4 antes de enviarla: contra el esquema oficial, sus cuentas y los datos de Hacienda. Lo hice pensando en la facturación electrónica, donde cada línea de una factura necesita su código CABYS y el IVA correcto, y un error se descubre cuando Hacienda rechaza el comprobante.
Está publicado en npm y en el registro oficial de MCP
como io.github.jmnzcn/mcp-hacienda-cr.

Grabado con MCP Inspector contra la API real de Hacienda: el tipo de cambio del día, los códigos CABYS de "café tostado" con su IVA y la situación tributaria de la CNFL.
Qué le podés preguntar 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 del 1 %, pero2391102020000(café tostado descafeinado) paga 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 · 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.
"Revisá esta factura antes de que la envíe" (con el XML adjunto)
❌ Factura electrónica tiene 1 error y 1 advertencia.
Esquema oficial 4.4: cumple (validado como borrador, sin firma)
❌ Resumen › TotalComprobante: dice 26 980,00, pero venta neta + impuesto + otros cargos − IVA devuelto da 26 880,00 (diferencia 100,00).
⚠️ Línea 2 › Impuesto › Tarifa: cobra IVA 13 %, pero el CABYS 0161001010000 (café cereza, orgánico) tiene 1 %.
También: "¿A cuánto está el dólar hoy?" o "¿La exoneración AL-00460853-20 sigue vigente?". Son respuestas reales del servidor contra la API de Hacienda.
Related MCP server: costa-rica-invoice-mcp
Herramientas
tipo_de_cambio: el tipo de cambio de referencia del día, dólar (compra y venta) y euro.consultar_contribuyente: nombre, tipo de identificación, régimen, estado, si está moroso u omiso y sus actividades económicas. Ejemplo:3-101-000046.buscar_cabys: busca códigos CABYS por descripción, con su tarifa de IVA. Ejemplo:café tostado.obtener_cabys: el detalle de un código CABYS, con su IVA y su categoría. Ejemplo:0161001010000.consultar_exoneracion: beneficiario, porcentaje, vigencia y códigos CABYS que cubre una exoneración. Ejemplo:AL-00460853-20.validar_factura: revisa el XML de un comprobante 4.4, firmado o sin firmar, y explica cada problema en español. Ejemplo: examples/factura-con-errores.xml.
Todas son de solo lectura y usan las APIs públicas de Hacienda, así que no hace falta registrarse ni tener una API key.
Instalación
Requiere Node.js 18 o superior.
En Claude Desktop, agregalo a claude_desktop_config.json (Configuración → Desarrollador → Editar
configuración):
{
"mcpServers": {
"hacienda-cr": {
"command": "npx",
"args": ["-y", "mcp-hacienda-cr"]
}
}
}En Claude Code:
claude mcp add hacienda-cr -- npx -y mcp-hacienda-crEn Cursor, VS Code y otros clientes MCP, usá el comando npx -y mcp-hacienda-cr con transporte stdio.
Qué revisa validar_factura
Sirve para los ocho tipos de comprobante 4.4: factura, tiquete, notas de crédito y de débito, factura de compra, factura de exportación, recibo electrónico de pago y mensaje receptor.
El esquema oficial. Valida el XML contra los XSD de Hacienda en la revisión vigente desde el 1 de noviembre de 2026 (vienen incluidos; su origen está en schemas/v4.4/FUENTE.md). Si el comprobante no está firmado, lo valida como borrador y lo avisa. Si usa el espacio de nombres de la versión 4.3, lo dice.
Las cuentas. Revisa cada línea y el resumen con las fórmulas que documentan los propios esquemas: cantidad × precio, descuentos, IVA según la tarifa, impuesto neto, total de la línea, gravado + exento + exonerado + no sujeto, venta neta, desglose por tarifa, total del comprobante y medios de pago. Compara al céntimo.
La clave y el consecutivo. Comprueba que la clave de 50 posiciones tenga la fecha, la identificación del emisor y el consecutivo del documento, y que el consecutivo sea del tipo de comprobante correcto.
Los datos de Hacienda. Comprueba que el emisor y el receptor estén registrados, que la actividad económica sea del emisor, que cada CABYS exista y cobre su IVA, que cada exoneración exista, esté vigente, sea del receptor y cubra el CABYS, y que el tipo de cambio en dólares se parezca al de referencia del día. Si Hacienda no responde, lo avisa sin invalidar el comprobante.
No verifica la firma criptográficamente ni reemplaza la aceptación de Hacienda: es una revisión previa para no enviar comprobantes que van a ser rechazados.
Cómo funciona
flowchart LR
U["Usuario"] --> A["Asistente de IA<br/>(Claude, Cursor…)"]
A -- "MCP (stdio)" --> S["mcp-hacienda-cr"]
S -- "HTTPS" --> H["api.hacienda.go.cr"]Está escrito en TypeScript con el SDK oficial de MCP,
y cada herramienta valida su entrada con Zod antes de llamar a Hacienda: una cédula física tiene 9
dígitos, una jurídica o NITE 10, un DIMEX 11 o 12, y un código CABYS 13. Cada respuesta trae un texto
legible para la conversación y los datos exactos en structuredContent para que el modelo trabaje
con ellos. Si la cédula no es válida, el código no existe o la API de Hacienda está caída, el usuario
recibe un mensaje claro en vez de un error. Las respuestas quedan en caché 10 minutos (tipo de cambio)
o una hora (lo demás) para no saturar la API.
Pruebas
Hay 44 pruebas unitarias del cliente, el validador y el servidor completo, con un cliente MCP real en memoria y respuestas de Hacienda grabadas. Las del validador parten de una factura que cuadra y la rompen de a un error por vez. Además, el validador se probó con los siete comprobantes de ejemplo de DojoCodingLabs/hacienda-cr, generados por otro proyecto: todos pasan. Aparte, unas pruebas de contrato llaman a la API real para detectar si Hacienda cambia el formato de sus respuestas, y una prueba de humo levanta el servidor compilado por stdio, como lo haría Claude, y llama a las seis herramientas. El CI corre en Node 18, 20 y 22 en cada push, y las pruebas contra la API real también cada lunes, para enterarme antes que los usuarios si algo cambia.
npm install
npm test # unitarias, sin red
npm run test:live # contrato con la API real de Hacienda
npm run smoke # servidor compilado por stdio, de punta a puntaAviso
Los datos vienen de las APIs públicas del Ministerio de Hacienda y son de referencia. Este proyecto no está afiliado al Ministerio de Hacienda. Las decisiones fiscales confirmalas con un contador o directamente con Hacienda.
Licencia
PolyForm Noncommercial 1.0.0. Podés usarlo gratis para fines no comerciales: uso personal,
investigación, educación o para evaluarlo. Cualquier uso comercial necesita una licencia:
neyfred@gmail.com. Las versiones hasta el commit 438da02 (2026-10-26),
incluida la 0.1.1 publicada en npm, se publicaron con licencia MIT.
English summary
mcp-hacienda-cr is a Model Context Protocol server that lets AI assistants such as Claude and Cursor query the public APIs of Costa Rica's Ministry of Finance: official exchange rates, taxpayer status (registered, delinquent or non-filer, economic activities), CABYS product and service codes with their VAT rate, and tax exemptions. It also validates a v4.4 e-invoice XML before it is sent: against the official schemas, its own arithmetic, and Hacienda's data (taxpayers, CABYS VAT rates, exemptions), explaining each problem in Spanish. It is aimed at e-invoicing, where every invoice line needs a CABYS code and the right VAT rate. No API key is needed. It is listed in the official MCP registry and installs with one command:
claude mcp add hacienda-cr -- npx -y mcp-hacienda-crAvailable Tools
5 toolsbuscar_cabysBuscar código CABYSARead-only
Busca en el catálogo CABYS (Catálogo de Bienes y Servicios) los códigos que corresponden a un producto o servicio, con su tarifa de IVA. Todo bien o servicio de una factura electrónica en Costa Rica necesita su código CABYS.
Inputs: descripcion (required), limite.
consultar_contribuyenteConsultar contribuyenteARead-only
Situación tributaria de una persona o empresa en Hacienda a partir de su cédula física, jurídica, DIMEX o NITE: nombre, régimen, estado, si está morosa u omisa y sus actividades económicas. Útil antes de emitir una factura electrónica.
Inputs: identificacion (required).
consultar_exoneracionConsultar exoneraciónARead-only
Datos de una exoneración de impuestos registrada en Hacienda a partir de su número de autorización: beneficiario, porcentaje, vigencia y códigos CABYS que cubre.
Inputs: autorizacion (required).
obtener_cabysDetalle de un código CABYSARead-only
Descripción, tarifa de IVA y categorías de un código CABYS de 13 dígitos.
Inputs: codigo (required).
tipo_de_cambioTipo de cambio del díaARead-only
Tipo de cambio de referencia de hoy según Hacienda: dólar (compra y venta en colones) y euro (en colones y en dólares).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a clearly distinct resource: exchange rates, taxpayer status, CABYS search, CABYS lookup by code, and tax exoneration details. buscar_cabys and obtener_cabys are adjacent but clearly differentiated as search versus direct code lookup.
Four tools follow a consistent Spanish verb_noun pattern: consultar_contribuyente, buscar_cabys, obtener_cabys, consultar_exoneracion. The outlier tipo_de_cambio is a noun phrase rather than an action, but it is still clear and readable.
Five tools is well-scoped for a focused Hacienda CR lookup server. Each tool supports a distinct e-invoicing or tax-reference need without unnecessary surface area.
The set covers the core reference lookups implied by the domain: exchange rates, taxpayer status, CABYS catalog search/detail, and exonerations. Minor gaps may exist around broader Hacienda services or historical/currency variants, but agents can work around them for typical e-invoicing preparation.
Maintenance
Related MCP Connectors
Costa Rica Hacienda v4.4: AI agents submit and query electronic invoices, stateless BYO.
Ecuador factura electronica for AI agents - issue and query SRI e-invoices via Datil. Stateless BYO.
Chile DTE for AI agents - boleta/factura electronica via OpenFactura or LibreDTE. Stateless BYO.
Live & historical FX rates and currency conversion for AI agents. No API keys.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to accept payments in Costa Rica through ONVO Pay, providing tools to create payment links and query payment status.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to submit already-signed Costa Rica electronic invoices (v4.4) to the Ministerio de Hacienda e-invoicing gateway, handling authentication and submission while keeping signing on the user's side.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to issue and query Paraguay SIFEN e-Kuatia electronic invoices through FacturaSend, handling IVA math and stateless forwarding.MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI assistants to query and analyze Costa Rica's public procurement (SICOP) data, including supplier profiles, market trends, product price histories, and bid comparisons, through a suite of MCP tools.-