weather-mcp

Servidor MCP (Model Context Protocol) de previsão do tempo. Recebe o nome de uma cidade (ex.: Recife,BR) e retorna a previsão usando a API do OpenWeather via PyOWM.

O transporte é Streamable HTTP, então o servidor sobe em http://127.0.0.1:8000/mcp e pode ser consumido por qualquer cliente MCP.

O código do servidor cabe em ~30 linhas (server.py) — feito para servir de demo/exemplo em apresentações.

Getting Started

1. Pré-requisitos

• Python 3.12+
• uv (gerenciador de pacotes/projeto)
• Uma API Key do OpenWeather — crie uma conta gratuita em https://home.openweathermap.org/api_keys

2. Setup do projeto

# instala as dependências no ambiente virtual do projeto
uv sync

3. Configuração da API Key

A chave é lida da variável de ambiente OPENWEATHER_API_KEY.

export OPENWEATHER_API_KEY="sua_chave_aqui"

Dica: você também pode criar um arquivo .env e carregá-lo (ex.: export $(cat .env | xargs)), mas exportar a variável já é suficiente.

4. Execução

uv run python server.py

Saída esperada:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

O endpoint MCP fica disponível em http://127.0.0.1:8000/mcp.

5. Teste rápido (opcional)

Use o inspector oficial para explorar o servidor pelo navegador:

npx @modelcontextprotocol/inspector

No inspector, escolha o transporte Streamable HTTP e aponte para http://127.0.0.1:8000/mcp. A tool disponível é get_forecast(city).

Configuração nos clientes MCP

Deixe o servidor rodando (uv run python server.py) antes de configurar os clientes abaixo. Todos apontam para o mesmo endpoint HTTP.

VSCode + GitHub Copilot

Crie o arquivo .vscode/mcp.json na raiz do workspace:

{
  "servers": {
    "weather": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Abra o Copilot Chat no modo Agent, clique no ícone de ferramentas e confirme que a tool get_forecast aparece.

Claude Code

Registre o servidor com transporte HTTP:

claude mcp add --transport http weather http://127.0.0.1:8000/mcp

Verifique com claude mcp list. Dentro de uma sessão, use /mcp para inspecionar o servidor e suas tools.

Codex

No arquivo de configuração ~/.codex/config.toml, adicione:

[mcp_servers.weather]
url = "http://127.0.0.1:8000/mcp"

Dependendo da versão do Codex CLI, o suporte a transporte HTTP exige habilitar o cliente RMCP. Se o servidor não conectar, adicione ao topo do ~/.codex/config.toml:

experimental_use_rmcp_client = true

Como funciona

# server.py
mcp = FastMCP("weather")
owm = OWM(os.environ["OPENWEATHER_API_KEY"])

@mcp.tool()
def get_forecast(city: str) -> str:
    forecast = owm.weather_manager().forecast_at_place(city, "3h").forecast
    ...

mcp.run(transport="streamable-http")

• FastMCP expõe a função decorada com @mcp.tool() como uma tool MCP.
• forecast_at_place(city, "3h") usa a previsão gratuita de 5 dias / 3 horas do OpenWeather.
• transport="streamable-http" sobe o servidor HTTP em /mcp.

Exemplo de uso

Pergunte ao seu assistente:

Qual a previsão do tempo para Recife?

Ele chamará get_forecast("Recife,BR") e responderá com base no retorno da tool.