mcp-servicos-pt

Servidor MCP de serviços portugueses. Primeiro conector: IPMA (meteorologia) — API pública, sem chave, sem autenticação.

Estrutura

src/mcp_servicos_pt/
├── server.py              # monta o servidor, regista conectores
├── __main__.py            # ponto de entrada (`python -m mcp_servicos_pt`)
├── core/connector.py       # contrato que cada conector cumpre
└── connectors/ipma/
    ├── client.py           # HTTP puro, fala com api.ipma.pt — sem MCP
    ├── models.py           # traduz a resposta bruta para JSON legível
    └── connector.py        # regista as tools no servidor MCP

Related MCP server: IPMA MCP Server

Instalar

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Testar a lógica (sem rede)

pytest tests/ -v

Correr o servidor e testar com o MCP Inspector

O Inspector é a ferramenta oficial para testar um servidor MCP visualmente, sem precisar de configurar o Claude Desktop.

npx @modelcontextprotocol/inspector python -m mcp_servicos_pt

Abre o URL que aparece no terminal, clica em "List Tools" e devem aparecer listar_localidades_pt e previsao_tempo_pt. Chama listar_localidades_pt primeiro para obteres um globalIdLocal válido, e usa-o depois em previsao_tempo_pt.

Ligar ao Claude Desktop

No ficheiro de configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS, ou o equivalente no Windows/Linux), acrescenta:

{
  "mcpServers": {
    "servicos-pt": {
      "command": "/caminho/completo/para/.venv/bin/python",
      "args": ["-m", "mcp_servicos_pt"],
      "cwd": "/caminho/completo/para/mcp-servicos-pt"
    }
  }
}

Reinicia o Claude Desktop e pergunta algo como "que tempo vai fazer em Lisboa nos próximos dias?" — o modelo deve encadear as duas tools sozinho.

Nota importante sobre os nomes dos campos do IPMA

Este projeto foi construído num ambiente sem acesso de rede a api.ipma.pt, por isso os nomes dos campos em models.py (tMin, tMax, idWeatherType, forecastDate, ...) vêm da documentação pública conhecida do IPMA, mas não foram confirmados com uma chamada real. O código foi escrito de forma defensiva (usa .get() em vez de aceder direto às chaves), por isso não deve rebentar mesmo que um nome tenha mudado — mas antes de confiares nos valores, corre listar_localidades_pt e previsao_tempo_pt no teu ambiente, compara com a resposta bruta em https://api.ipma.pt/open-data/ e ajusta models.py se algum campo não bater certo. O resto da arquitetura não muda.

Próximo passo

Para adicionar um segundo serviço (ex. dados.gov.pt):

1. Cria connectors/dados_gov/{client,models,connector}.py seguindo exatamente o mesmo padrão do IPMA.

2. Regista-o em server.py: DadosGovConnector().register(mcp)

Nada no núcleo precisa de mudar.