bhuppal/mcp_server_weather

MCP server: Open-Meteo weather example

This repository contains a minimal MCP (Model Connector Protocol) server that demonstrates how to expose weather data and tools to language models using the Open-Meteo API. The example is intentionally small and local so it's easy to run with the Claude Desktop app (or other MCP clients).

Overview

MCP servers extend the capabilities of language models by connecting them to data sources and services. They expose three main primitives:

• Resources (client-controlled): exposes data to be used as context on request. Use for passive data access.
• Tools (model-controlled): exposes executable functionality the model can call to fetch or transform data.
• Prompts (user-controlled): reusable prompts and workflows surfaced to users.

This example focuses on building a small MCP server that exposes tools to fetch current weather and forecasts from the Open-Meteo API.

Why Open-Meteo?

• Free for non-commercial use and requires no API key.
• Configurable through query parameters (hourly, daily, current, geocoding).
• Well suited for LLM integrations where you want raw structured data returned to the model.

Contents

• server.py — the MCP server entrypoint used by this tutorial.
• pyproject.toml — project metadata and dependencies.
• README.md — this file.

Requirements

• A Claude.ai account and the Claude Desktop app (for MCP client testing).
• A code editor (VS Code recommended).
• uv (Rust-based Python package manager) — install via Homebrew on macOS:

brew install uv

Or on Windows via winget:

winget install --id=astral-sh.uv -e

Quick setup (recommended workflow)

1. Create the project folder and open it in your editor (if you haven't already):

mkdir mcp-server-weather
cd mcp-server-weather

2. Initialize a uv project and virtual environment, then install runtime dependencies:

uv init
uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx

Notes:

• Use deactivate to exit the virtual environment.
• This repository already contains pyproject.toml and server.py — you can skip creating files and run the server directly.

Scaffolding the MCP server (example)

A minimal server.py for this tutorial contains:

• Strong typing and httpx for HTTP requests
• FastMCP from the Python MCP SDK for building MCP servers
• A helper to call the Open-Meteo API
• One or more @mcp.tool() functions that return raw JSON to the model

Example snippets (already implemented in server.py):

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("weather")

# Constants
OPENMETEO_API_BASE = "https://api.open-meteo.com/v1"
USER_AGENT = "weather-app/1.0"

async def make_openmeteo_request(url: str) -> dict[str, Any] | None:
    headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

@mcp.tool()
async def get_current_weather(latitude: float, longitude: float) -> str:
    """Get current weather for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    url = f"{OPENMETEO_API_BASE}/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m,is_day,showers,cloud_cover,wind_speed_10m,wind_direction_10m,pressure_msl,snowfall,precipitation,relative_humidity_2m,apparent_temperature,rain,weather_code,surface_pressure,wind_gusts_10m"
    data = await make_openmeteo_request(url)
    if not data:
        return "Unable to fetch current weather data for this location."
    return data

if __name__ == "__main__":
    mcp.run(transport='stdio')

Notes on tools

• Tools are defined using @mcp.tool().
• The initial function docstring acts as the tool's prompt for the LLM (explain when/how to use it).
• Tools should return structured data (avoid pre-formatting for human display) so the LLM can interpret and render it.

Running and testing the MCP server

1. Start the MCP server in developer mode (this will also run the MCP Inspector):

mcp dev server.py

2. Open the MCP Inspector at http://localhost:5173
3. Click "Connect" and open the "Tools" tab
4. Use "List Tools" to discover available tools and run get_current_weather with a latitude/longitude (for example: 63.4463991, 10.8127596).
5. Inspect the raw JSON under "Tool Result".

Extending the server

• get_forecast — return hourly/daily forecasts with a configurable range.
• get_location — use the Open-Meteo Geocoding API to translate place names to coordinates.
• Add Resources to expose cached or aggregated weather summaries to clients.

Troubleshooting

• If the MCP server doesn't behave as expected, compare it to the reference open-meteo-weather example from the course materials.
• Check the terminal output where you ran mcp dev server.py for stack traces.
• Make sure your virtual environment is activated and mcp[cli] and httpx are installed in that environment.

License

This project is provided as an example for learning purposes. Use and modify freely.

If you'd like, I can also:

• Add a small CONTRIBUTING.md with development tips and testing steps.
• Add a minimal requirements.txt or update pyproject.toml to explicitly list dependencies.
• Add a short example server.py or tests if you want me to create/modify files in this repo.