guatemala-mcp

An open-source Model Context Protocol (MCP) server that exposes Guatemalan public data and validation utilities to AI assistants. The first MCP server built specifically for Guatemala.

No API keys required. Works with Claude Desktop, Cursor, and any MCP-compatible client.

Quick start

npx guatemala-mcp

Or install globally:

npm install -g guatemala-mcp
guatemala-mcp

Tools

validate_nit

Validate a Guatemalan NIT (Número de Identificación Tributaria) using the official modulo-11 check-digit algorithm.

Request:

{ "nit": "576937-K" }

Response:

{
  "nit_normalized": "576937-K",
  "is_valid": true,
  "reason_if_invalid": null
}

Accepts input with or without hyphen (576937-K or 576937K).

validate_cui

Validate a Guatemalan CUI/DPI (Código Único de Identificación) — checks format, modulo-11 check digit, and department/municipality codes against RENAP's structure.

Request:

{ "cui": "1234567890101" }

Response:

{
  "cui_normalized": "1234567890101",
  "is_valid": true,
  "department": "Guatemala",
  "municipality": 1,
  "reason_if_invalid": null
}

Accepts input with or without spaces/hyphens (1234 56789 0101).

get_holidays

List official Guatemalan national holidays (asuetos) for a given year, per Código de Trabajo Art. 127. Includes fixed dates and movable Holy Week dates computed via Easter computus.

Request:

{ "year": 2026 }

Response:

[
  { "date": "2026-01-01", "name": "Año Nuevo", "type": "national" },
  { "date": "2026-04-02", "name": "Jueves Santo", "type": "national" },
  { "date": "2026-04-03", "name": "Viernes Santo", "type": "national" },
  { "date": "2026-04-04", "name": "Sábado Santo", "type": "national" },
  { "date": "2026-05-01", "name": "Día del Trabajo", "type": "national" },
  { "date": "2026-06-30", "name": "Día del Ejército", "type": "national" },
  { "date": "2026-09-15", "name": "Día de la Independencia", "type": "national" },
  { "date": "2026-10-20", "name": "Día de la Revolución", "type": "national" },
  { "date": "2026-11-01", "name": "Día de Todos los Santos", "type": "national" },
  { "date": "2026-12-24", "name": "Nochebuena (medio día)", "type": "national" },
  { "date": "2026-12-25", "name": "Navidad", "type": "national" },
  { "date": "2026-12-31", "name": "Fin de Año (medio día)", "type": "national" }
]

The year parameter is optional and defaults to the current year.

get_exchange_rate

Get the official Banguat (Banco de Guatemala) USD to GTQ reference exchange rate.

Request:

{ "date": "2026-06-22" }

Response:

{
  "date": "2026-06-22",
  "rate_gtq_per_usd": 7.62308,
  "source": "Banguat"
}

The date parameter is optional (defaults to today). Data comes directly from Banguat's public SOAP service — no API key needed.

Using with Claude Desktop

Add this to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop. The tools will appear automatically.

Using with MCP Inspector

npx @modelcontextprotocol/inspector npx guatemala-mcp

This opens a browser UI where you can test each tool interactively.

Development

git clone https://github.com/YOUR_USERNAME/guatemala-mcp.git
cd guatemala-mcp
npm install
npm run build
npm test

Run the dev server:

npm run dev

Data sources

| Tool | Source | Auth | |------|--------|------| | validate_nit | Modulo-11 algorithm | None (offline) | | validate_cui | RENAP / Minfin | None (offline) | | get_holidays | Código de Trabajo, Art. 127 | None (offline) | | get_exchange_rate | Banguat SOAP service | None (public) |

License

MIT