Guia Prático: Criando seu Primeiro Servidor MCP em Python

# weather.py

import os
from typing import Any, Optional

import httpx
from dotenv import load_dotenv
from mcp.server.fastmcp import FastMCP

# Inicializa o servidor com um nome descritivo
mcp = FastMCP("weather-brazil-server")

# URLs base das APIs e um User-Agent para boas práticas
OPENWEATHER_API_BASE = "https://api.openweathermap.org/data/2.5"
USER_AGENT = "weather-brazil-mcp-server/1.0"

# Carrega as variáveis de ambiente (nossa API key)
load_dotenv()
OPENWEATHER_API_KEY = os.getenv("OPENWEATHER_API_KEY")

# weather.py (continuação)

async def make_request(url: str, params: dict) -> Optional[dict[str, Any]]:
    """Faz uma requisição GET assíncrona e retorna o JSON ou None em caso de erro."""
    headers = {"User-Agent": USER_AGENT}
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, params=params, headers=headers, timeout=30.0)
            response.raise_for_status()  # Lança um erro para respostas 4xx ou 5xx
            return response.json()
        except httpx.HTTPStatusError as e:
            print(f"Erro de HTTP: {e.response.status_code}")
            return None
        except httpx.RequestError as e:
            print(f"Erro na requisição: {e}")
            return None

# weather.py (continuação)

def format_current_weather(data: Optional[dict]) -> str:
    """Formata os dados do tempo atual em uma string amigável."""
    if not data:
        return "Não foi possível obter os dados do tempo."

    weather = data.get("weather", [{}])[0]
    main = data.get("main", {})
    wind = data.get("wind", {})

    return (
        f'Condições Atuais - {data.get("name", "Localização desconhecida")}\n\n'
        f'Temperatura: {main.get("temp", "N/A")}°C (Sensação: {main.get("feels_like", "N/A")}°C)\n'
        f'Condição: {weather.get("description", "N/A").title()}\n'
        f'Umidade: {main.get("humidity", "N/A")}%'
    )

def format_forecast(data: Optional[dict]) -> str:
    """Formata a previsão do tempo em uma string amigável."""
    if not data or "list" not in data:
        return "Não foi possível obter a previsão do tempo."

    city_name = data.get("city", {}).get("name", "Localização desconhecida")
    forecasts = [f"Previsão para {city_name}\n"]

    for item in data["list"][:5]:  # Pega os 5 próximos períodos
        dt_txt = item.get("dt_txt", "")
        main = item.get("main", {})
        weather = item.get("weather", [{}])[0]
        forecasts.append(
            f'\n---\n{dt_txt}\n'
            f'Temperatura: {main.get("temp", "N/A")}°C\n'
            f'Condição: {weather.get("description", "N/A").title()}'
        )

    return "".join(forecasts)

# weather.py (continuação)

@mcp.tool()
async def get_current_weather_city(city: str, state: str = "") -> str:
    """Obtém as condições meteorológicas atuais para uma cidade brasileira."""
    query = f"{city},{state},BR" if state else f"{city},BR"
    params = {"q": query, "appid": OPENWEATHER_API_KEY, "units": "metric", "lang": "pt_br"}
    data = await make_request(f"{OPENWEATHER_API_BASE}/weather", params)
    return format_current_weather(data)

@mcp.tool()
async def get_forecast_city(city: str, state: str = "") -> str:
    """Obtém a previsão do tempo para uma cidade brasileira."""
    query = f"{city},{state},BR" if state else f"{city},BR"
    params = {"q": query, "appid": OPENWEATHER_API_KEY, "units": "metric", "lang": "pt_br"}
    data = await make_request(f"{OPENWEATHER_API_BASE}/forecast", params)
    return format_forecast(data)

@mcp.tool()
async def get_weather_coordinates(latitude: float, longitude: float) -> str:
    """Obtém as condições meteorológicas para coordenadas geográficas."""
    params = {"lat": latitude, "lon": longitude, "appid": OPENWEATHER_API_KEY, "units": "metric", "lang": "pt_br"}
    data = await make_request(f"{OPENWEATHER_API_BASE}/weather", params)
    return format_current_weather(data)

# weather.py (continuação)

CAPITAIS_BRASIL = {
    "acre": ("Rio Branco", "AC"), "alagoas": ("Maceió", "AL"),
    "amapá": ("Macapá", "AP"), "amazonas": ("Manaus", "AM"),
    "bahia": ("Salvador", "BA"), "ceará": ("Fortaleza", "CE"),
    "distrito federal": ("Brasília", "DF"), "espírito santo": ("Vitória", "ES"),
    "goiás": ("Goiânia", "GO"), "maranhão": ("São Luís", "MA"),
    "mato grosso": ("Cuiabá", "MT"), "mato grosso do sul": ("Campo Grande", "MS"),
    "minas gerais": ("Belo Horizonte", "MG"), "pará": ("Belém", "PA"),
    "paraíba": ("João Pessoa", "PB"), "paraná": ("Curitiba", "PR"),
    "pernambuco": ("Recife", "PE"), "piauí": ("Teresina", "PI"),
    "rio de janeiro": ("Rio de Janeiro", "RJ"), "rio grande do norte": ("Natal", "RN"),
    "rio grande do sul": ("Porto Alegre", "RS"), "rondônia": ("Porto Velho", "RO"),
    "roraima": ("Boa Vista", "RR"), "santa catarina": ("Florianópolis", "SC"),
    "são paulo": ("São Paulo", "SP"), "sergipe": ("Aracaju", "SE"),
    "tocantins": ("Palmas", "TO"),
}

@mcp.tool()
async def get_weather_state_capital(state: str) -> str:
    """Obtém as condições meteorológicas da capital de um estado brasileiro."""
    state_lower = state.lower()
    capital_info = None
    for state_name, info in CAPITAIS_BRASIL.items():
        if state_lower == state_name or state_lower == info[1].lower():
            capital_info = info
            break

    if not capital_info:
        return f"Estado '{state}' não encontrado. Tente o nome completo ou a sigla."

    return await get_current_weather_city(capital_info[0], capital_info[1])

# weather.py (continuação)

if __name__ == "__main__":
    if not OPENWEATHER_API_KEY or OPENWEATHER_API_KEY == "SUA_CHAVE_AQUI":
        print("❌ Erro: A chave da API do OpenWeatherMap não está configurada.")
        print("   Por favor, edite o arquivo .env e adicione sua chave.")
        exit(1)

    print("🌦️  Servidor MCP de Previsão do Tempo iniciado.")
    print("   Aguardando conexão de um host como o Claude for Desktop...")
    mcp.run()

{
  "mcpServers": {
    "weather": {
      "command": "/caminho/para/seu/.local/bin/uv",
      "args": [
        "run",
        "--cwd",
        "/caminho/para/seu/projeto/weather",
        "python",
        "weather.py"
      ]
    }
  }
}