mcp-pt

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

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

Cursor

Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.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)

# 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, ipma-api, geoapi-pt-sdk, ine-pt and dados-gov-pt. The server is self-contained (it calls the APIs directly), so it has no dependency on those packages.

Develop

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 © Marcelo Domingues