mcp-portugal

A Model Context Protocol (MCP) server for Portuguese public data. Give any MCP-capable AI assistant (Claude Desktop, Claude Code, Cursor, …) reliable, deterministic tools to validate a NIF, an IBAN, a postal code, and to look up national holidays — no API keys, runs locally over stdio.

🌍 English · Português · 📚 Documentation

<p align="center"><img src="assets/demo.svg" alt="mcp-portugal tool calls" width="100%"></p>

Tools

Tool	Description
validate_nif	Validate a NIF (check digit) and classify the taxpayer type.
validate_iban	Validate an IBAN (ISO 7064 mod-97); flags PT IBANs.
validate_postal_code	Validate a CP7 postal code (NNNN-NNN).
list_holidays	National holidays for a year, including movable (Easter-based).
is_holiday	Whether a given YYYY-MM-DD is a national holiday.

Use with Claude Desktop / Claude Code

Add to your MCP config (e.g. claude_desktop_config.json, or .mcp.json for Claude Code):

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

Then ask: "Is 123456789 a valid NIF, and what type?" or "List the Portuguese holidays in 2026."

Run locally

npm install
npm start          # runs the stdio server (tsx)
npm test           # unit + stdio integration tests
npm run build      # tsc -> dist/

To test it by hand with the MCP Inspector:

npx @modelcontextprotocol/inspector npx -y mcp-portugal

Roadmap

• Postal-code → locality lookup (CTT open data)
• ATCUD / invoice QR-code composition (via pt-fiscal)
• IBAN → bank name resolution

Contributions welcome — see CONTRIBUTING.md.

License

MIT © Marcelo Domingues