Getting started & client setup¶

mcp-portugal is a Model Context Protocol server. It exposes tools over stdio that an MCP client (an AI assistant) can call. You don't run it directly for daily use — you register it with your client.

Requirements¶

Node.js 20 or newer

Claude Desktop¶

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

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

Restart Claude Desktop. The tools appear under the 🔌 menu.

Claude Code¶

Add an .mcp.json at your project root (or use claude mcp add):

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

Cursor / other MCP clients¶

Any MCP client that supports stdio servers works — point it at npx -y mcp-portugal.

Try it without a client¶

Use the official MCP Inspector:

npx @modelcontextprotocol/inspector npx -y mcp-portugal

Then call, for example, list_holidays with { "year": 2026 }.

Run from source¶

git clone https://github.com/marcelogdomingues/mcp-portugal
cd mcp-portugal
npm install
npm start     # stdio server
npm test      # unit + stdio integration tests

Example prompts¶

"Is 123456789 a valid NIF, and what kind of taxpayer is it?"
"Validate the IBAN PT50 0002 0123 1234 5678 9015 4."
"List the Portuguese national holidays in 2026."
"Is 2026-04-25 a holiday in Portugal?"