# 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](README.md)** · [Português](README.pt.md) · 📚 [Documentation](docs/README.md)

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

[![CI](https://github.com/marcelogdomingues/mcp-portugal/actions/workflows/ci.yml/badge.svg)](https://github.com/marcelogdomingues/mcp-portugal/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/mcp-portugal.svg)](https://www.npmjs.com/package/mcp-portugal)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-6E56CF.svg)](https://modelcontextprotocol.io)

## 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):

```json
{
  "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

```bash
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:

```bash
npx @modelcontextprotocol/inspector npx -y mcp-portugal
```

## Roadmap

- Postal-code → locality lookup (CTT open data)
- ATCUD / invoice QR-code composition (via [`pt-fiscal`](https://github.com/marcelogdomingues/pt-fiscal))
- IBAN → bank name resolution

Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT © Marcelo Domingues