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

Tools

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