Skip to main content
Glama
Sign In
mcp-portugal

mcp-portugal

by marcelogdomingues
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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

CI npm License: MIT MCP

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.

Related MCP server: brasil-mcp-essentials

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

Available Tools

5 tools
is_holidayÉ feriado?A

Indica se uma data (YYYY-MM-DD) é feriado nacional em Portugal.

Inputs: date (required).

list_holidaysFeriados nacionaisA

Lista os feriados nacionais obrigatórios de Portugal para um ano, incluindo os móveis (baseados na Páscoa).

Inputs: year (required).

validate_ibanValidar IBANA

Valida um IBAN (checksum ISO 7064 mod-97). Indica também se é um IBAN português válido.

Inputs: iban (required).

validate_nifValidar NIFA

Valida um NIF português (estrutura, dígito inicial e dígito de controlo) e devolve o tipo de contribuinte.

Inputs: nif (required).

validate_postal_codeValidar código postalA

Valida o formato de um código postal português (CP7, NNNN-NNN).

Inputs: postalCode (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct domain concept: NIF, IBAN, postal code, holiday listing, and holiday checking. There is no overlap or ambiguity between them, and the descriptions make the purpose of each tool immediately clear.

    Naming Consistency4/5

    The naming mostly follows a consistent verb_noun pattern: validate_nif, validate_iban, validate_postal_code, list_holidays, is_holiday. The main deviation is the use of 'is_holiday' instead of 'validate_holiday', but this is still readable and predictable.

    Tool Count5/5

    With 5 tools, the server is well-scoped to Portugal-specific validation and holiday data. Each tool fills a clear niche without redundancy, and the count is appropriate for the domain.

    Completeness4/5

    The set covers common Portuguese data validation needs (NIF, IBAN, postal code) and national holidays comprehensively. A minor gap is the lack of validation for other Portuguese identifiers like NIPC, but NIF validation already covers taxpayer types, making this a workable surface.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • @openar/mcp

      @openar/mcpofficial

      openar-pt
      A
      license
      A
      quality
      D
      maintenance
      MCP server for Portuguese Parliament open data, enabling AI agents to access legislative initiatives, deputies, plenary votes, petitions, and parliamentary committees.
      12
      8 npm
      MIT

    • OpenUKPublicDataMCP

      HappyMonkeyAI
      A
      license
      C
      quality
      C
      maintenance
      A no-key-first MCP server providing access to UK public data including postcodes, bank holidays, carbon intensity, flood warnings, and government datasets.
      12
      26
      1
      MIT

    • mcp-bpstat-pt

      pipeworx-io
      A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for accessing BPstat (Banco de Portugal) statistics API without API keys. Enables querying Portuguese central bank data through natural language.
      293 npm
      MIT