<p align="center">
  <img src="./.github/assets/banner.svg" alt="mcp-pt — an MCP server for Portuguese public data" width="100%">
</p>

<p align="center">
  <b>A <a href="https://modelcontextprotocol.io">Model Context Protocol</a> (MCP) server that gives AI assistants live tools for <b>Portuguese public data</b>.</b><br>
  Fuel prices, weather (IPMA), postal codes &amp; geocoding (GeoAPI.pt), statistics (INE) and open data (dados.gov.pt) — usable from Claude, Cursor and any MCP host.
</p>

<p align="center">
  <a href="https://github.com/marcelogdomingues/mcp-pt/actions/workflows/ci.yml"><img src="https://github.com/marcelogdomingues/mcp-pt/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://www.npmjs.com/package/mcp-pt"><img src="https://img.shields.io/npm/v/mcp-pt.svg" alt="npm"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/MCP-server-8b5cf6" alt="MCP server">
</p>

<p align="center"><a href="https://marcelogdomingues.github.io/mcp-pt/"><b>📖 Documentation site</b></a></p>

> [!IMPORTANT]
> This is an **unofficial** community project. It is **not** affiliated with the data providers (DGEG, IPMA, INE, GeoAPI.pt, AMA/dados.gov.pt). Respect each provider's terms — in particular, DGEG fuel data is for **non-commercial** use.

---

## What it does

Ask your AI assistant things like:

- *"Qual o posto de gasóleo mais barato no distrito de Lisboa?"*
- *"Vai chover amanhã no Porto? Há avisos meteorológicos ativos?"*
- *"Que localidade tem o código postal 1990-096?"*
- *"Quantos habitantes tinha Portugal nos Censos 2021?"*
- *"Procura datasets sobre ambiente no dados.gov.pt."*

…and it will call the right tool, hit the public API, and answer with real data.

## Install

Run it with **npx** (no install needed) — just point your MCP host at it.

### Claude Desktop

Add to `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows):

```json
{
  "mcpServers": {
    "pt": {
      "command": "npx",
      "args": ["-y", "mcp-pt"]
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pt": { "command": "npx", "args": ["-y", "mcp-pt"] }
  }
}
```

### Any MCP host

The server speaks MCP over **stdio**. Launch `npx -y mcp-pt` (or `node dist/index.js` from a clone) as the server command.

## Tools

| Tool | What it does | Source |
| --- | --- | --- |
| `fuel_prices` | Cheapest fuel stations in a district (gasolina / gasóleo / GPL) | DGEG |
| `weather_forecast` | 5-day forecast for a location | IPMA |
| `weather_warnings` | Active meteorological warnings | IPMA |
| `postal_code` | Look up a código postal | GeoAPI.pt |
| `reverse_geocode` | Coordinate → district / municipality / parish | GeoAPI.pt |
| `municipality` | Municipality (concelho) details | GeoAPI.pt |
| `ine_indicator` | Fetch an INE statistics indicator by `varcd` | INE |
| `open_data_search` | Search datasets on dados.gov.pt | dados.gov.pt |

All tools call **free, public** APIs and need **no API keys**.

## Example (raw MCP)

```bash
# List the tools over stdio
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | npx -y mcp-pt
```

## How it relates to the SDKs

`mcp-pt` is the AI-facing layer over a family of standalone, multi-language SDKs
for the same data — [`precos-combustiveis-pt`](https://github.com/marcelogdomingues/precos-combustiveis-pt),
[`ipma-api`](https://github.com/marcelogdomingues/ipma-api),
[`geoapi-pt-sdk`](https://github.com/marcelogdomingues/geoapi-pt-sdk),
[`ine-pt`](https://github.com/marcelogdomingues/ine-pt) and
[`dados-gov-pt`](https://github.com/marcelogdomingues/dados-gov-pt). The server is
self-contained (it calls the APIs directly), so it has no dependency on those
packages.

## Develop

```bash
npm install
npm test        # vitest
npm run build   # tsup → dist/index.js (executable)
node dist/index.js
```

## FAQ

<details>
<summary><b>Does it need API keys?</b></summary>

No. Every tool uses a free, public Portuguese API.
</details>

<details>
<summary><b>Is it affiliated with the data providers?</b></summary>

No — it's an independent community project. Please respect each provider's terms (DGEG fuel data is non-commercial).
</details>

<details>
<summary><b>Which MCP hosts work?</b></summary>

Anything that speaks MCP over stdio — Claude Desktop, Cursor, Continue, and custom clients using the MCP SDK.
</details>

## License

[MIT](./LICENSE) © Marcelo Domingues