Skip to main content
Glama

šŸŒ”ļø MCP Weather Server

Python Version Model Context Protocol FastMCP

Um servidor MCP (Model Context Protocol) desenvolvido em Python que fornece uma interface de usuÔrio interativa e ferramentas backend para consulta de temperatura em tempo real em qualquer cidade do mundo. O projeto utiliza a API pública e gratuita da Open-Meteo (sem necessidade de chave de API) e renderiza as informações utilizando componentes visuais declarativos de UI.


šŸŽÆ Objetivo

O principal objetivo deste projeto Ć© estender as capacidades de assistentes de IA (como Claude Desktop ou outros clientes MCP) permitindo que eles:

  1. Apresentem um formulƔrio interativo de pesquisa de clima diretamente na interface de chat.

  2. Busquem dados meteorológicos em tempo real por meio de ferramentas baseadas no protocolo MCP.

  3. Exibam o resultado formatado em um card estilizado e amigƔvel para o usuƔrio.


Related MCP server: weather-mcp

šŸ› ļø Tecnologias Utilizadas

O projeto foi construĆ­do utilizando tecnologias modernas e eficientes no ecossistema Python:

  • Python (>= 3.14): Linguagem de programação base do projeto.

  • Model Context Protocol (MCP): Protocolo aberto que possibilita a comunicação estruturada de ferramentas e interfaces entre modelos de IA e servidores locais/remotos.

  • FastMCP (com suporte a [apps]): Framework moderno para criação rĆ”pida de servidores MCP em Python, incluindo suporte integrado a aplicaƧƵes e interfaces visuais.

  • Prefab UI: Biblioteca para construção declarativa de componentes de interface de usuĆ”rio (como Card, Form, Column, Row, Text e controle de estado reativo).

  • HTTPX: Cliente HTTP para Python, utilizado para realizar as consultas assĆ­ncronas/sĆ­ncronas Ć s APIs de geocodificação e previsĆ£o do tempo.

  • Open-Meteo API:

    • Geocoding API: Para converter o nome da cidade informado em coordenadas geogrĆ”ficas (latitude e longitude).

    • Weather Forecast API: Para buscar a temperatura atual com base nas coordenadas obtidas.


šŸ“ Estrutura do Projeto

A estrutura do projeto Ć© minimalista e organizada da seguinte forma:

mcp_weather/
ā”œā”€ā”€ .gitignore            # Arquivos e pastas a serem ignorados pelo Git
ā”œā”€ā”€ .python-version       # Definição da versĆ£o do Python utilizada
ā”œā”€ā”€ pyproject.toml        # Configuração do projeto e suas dependĆŖncias (PEP 518/621)
ā”œā”€ā”€ uv.lock               # Arquivo de lock de dependĆŖncias gerado pelo gerenciador 'uv'
ā”œā”€ā”€ main.py               # Código-fonte principal contendo o servidor MCP e as ferramentas
└── README.md             # Documentação do projeto (este arquivo)

Detalhamento do main.py

  • Geolocalização e Clima (_get_current_temperature): Função auxiliar que faz chamadas HTTP seguras para o Open-Meteo, tratando erros comuns (como cidades nĆ£o encontradas ou indisponibilidade de API).

  • Ferramenta de Backend (get_temperature): Ferramenta registrada no FastMCP que recebe o payload do formulĆ”rio, valida os dados e executa a busca meteorológica.

  • Interface de UsuĆ”rio (consultar_temperatura): Ponto de entrada de UI do servidor. Ela define o estado inicial da aplicação, cria um formulĆ”rio dinĆ¢mico a partir de um modelo Pydantic e renderiza os cards de sucesso ou erro de forma condicional (If/Else).


šŸš€ Instalação e Execução

Este projeto utiliza o gerenciador de pacotes moderno uv. Caso não tenha o uv instalado, você pode utilizar o pip tradicional.

Opção 1: Executando com uv (Recomendado)

  1. Certifique-se de estar com o Python 3.14 ou superior configurado.

  2. Instale as dependĆŖncias e crie o ambiente virtual automaticamente:

    uv sync
  3. Execute o servidor localmente:

    uv run main.py

Opção 2: Executando com pip

  1. Crie e ative um ambiente virtual:

    python -m venv .venv
    # No Windows (PowerShell):
    .venv\Scripts\Activate.ps1
    # No Linux/macOS:
    source .venv/bin/activate
  2. Instale os pacotes necessƔrios:

    pip install "fastmcp[apps]>=3.4.2" "prefab>=1.6.0" httpx pydantic
  3. Execute o servidor:

    python main.py

šŸ” Testando com o MCP Inspector

O @modelcontextprotocol/inspector Ʃ uma ferramenta excelente para testar e depurar servidores MCP de forma rƔpida, sem a necessidade de configurƔ-los previamente em clientes complexos de IA.

Para testar este servidor com o inspetor, execute o seguinte comando no terminal:

npx @modelcontextprotocol/inspector uv run main.py

Isso iniciarĆ” o inspetor em seu navegador. Para verificar o resultado:

  1. Conecte-se ao servidor MCP pelo painel do Inspetor.

  2. Clique na aba Apps no menu do inspetor.

  3. Selecione o app MCP que consulta o clima na cidade informada para interagir com o formulƔrio e validar a resposta da temperatura.


šŸ”Œ Configuração no Claude Desktop

Para utilizar este servidor diretamente no Claude Desktop, adicione a configuração do servidor ao seu arquivo de configuração do Claude (claude_desktop_config.json).

Caminho do arquivo de configuração

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Exemplo de Configuração

Substitua o caminho executÔvel de acordo com o seu ambiente (usando uv para execução automÔtica):

{
  "mcpServers": {
    "mcp-weather": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\Gustavo\\workspace\\test\\mcp_weather",
        "run",
        "main.py"
      ]
    }
  }
}

Nota: Certifique-se de ajustar o caminho absoluto da pasta para corresponder exatamente à localização no seu computador.


šŸ’” Como Funciona a Interface

Ao interagir com um modelo de linguagem que suporta o servidor, o assistente pode acionar a ferramenta visual consultar_temperatura. O fluxo de execução funciona assim:

  1. Apresentação: O usuÔrio solicita o clima, e o modelo renderiza o formulÔrio consultar_temperatura.

  2. Entrada de Dados: O usuÔrio preenche o campo de texto com o nome da cidade desejada (ex: São Paulo ou Tokyo) e clica em Consultar.

  3. Processamento: O botão aciona a ferramenta de backend get_temperature via ação reativa CallTool.

  4. Atualização de Estado:

    • Se a busca for bem-sucedida, o estado weather_result Ć© atualizado com as coordenadas e temperatura atuais, exibindo um card azul com a temperatura e localização resolvida (ex: SĆ£o Paulo, Brazil).

    • Se ocorrer um erro (ex: cidade inexistente), a tela exibe uma mensagem de erro estilizada num card vermelho.

  5. Rodapé: Link de atribuição de dados para a API parceira Open-Meteo.

Available Tools

1 tool
consultar_temperaturaA

Mostra um formulƔrio para o usuƔrio informar o nome de uma cidade e exibe a temperatura atual dessa cidade. Chame esta ferramenta sempre que o usuƔrio quiser saber a temperatura de qualquer lugar.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no ambiguity. The tool's purpose is clearly described.

    Naming Consistency5/5

    With a single tool, naming consistency is inherently perfect. The name 'consultar_temperatura' follows a clear verb_noun pattern in Portuguese.

    Tool Count3/5

    A single tool for a weather server feels thin. While a simple temperature lookup might be acceptable, the server could benefit from additional tools for forecasts or other conditions, making the count borderline.

    Completeness2/5

    The tool only provides current temperature. Missing forecast, humidity, wind, and other common weather data creates significant gaps for a weather server, likely causing agent failures when more information is requested.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides weather information using Open-Meteo API without requiring an API key. Supports weather queries by city name or coordinates with customizable temperature units.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time and historical weather data for any city worldwide, including forecasts, air quality, and marine conditions, using the free Open-Meteo API.
      13 npm
      MIT