# openmeteo-mcp

[![CI](https://github.com/ariz-ahmad/weather-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ariz-ahmad/weather-mcp-server/actions/workflows/ci.yml)

An MCP server wrapping the [Open-Meteo](https://open-meteo.com/) geocoding and forecast
APIs. No API key required.

## Install

```bash
pip install git+https://github.com/ariz-ahmad/weather-mcp-server
```

## Run

Stdio (default, for local agent clients):

```bash
openmeteo-mcp
```

SSE (for remote/hosted clients):

```bash
openmeteo-mcp sse
# serves on http://localhost:8000/sse
```

## Tool reference

| Tool | Args | Returns |
|---|---|---|
| `geocode_city` | `city: str` | `{name, country, latitude, longitude}` |
| `get_forecast` | `latitude: float, longitude: float, days: int = 3` | `{forecast: [{date, condition, temp_max_c, temp_min_c, precipitation_mm}, ...]}` |
| `get_weather_by_city` | `city: str, days: int = 3` | `{location, forecast}` — geocode + forecast in one call |

## Resource

`weather://{city}` — read-only current-conditions summary for a city, e.g. `weather://Tokyo`.

## Prompt

`weather_report(city: str)` — template that asks an agent to produce a short, friendly
3-day weather report for a city using `get_weather_by_city`.

## Connect from an Agents SDK client

```python
from agents import Agent, Runner
from agents.mcp import MCPServerStdio, MCPServerStdioParams

async with MCPServerStdio(
    name="Weather Tools",
    params=MCPServerStdioParams(command="openmeteo-mcp", args=[]),
) as weather_server:
    agent = Agent(
        name="Weather Assistant",
        instructions="Use the weather tools to answer the user's question.",
        mcp_servers=[weather_server],
    )
    result = await Runner.run(agent, "What's the weather in Tokyo this week?")
    print(result.final_output)
```

See `client_stdio_test.py` and `client_sse_test.py` for full runnable examples of each
transport.

## Development

```bash
git clone https://github.com/ariz-ahmad/weather-mcp-server
cd weather-mcp-server
pip install -e ".[dev]"
pytest -v
```

`tests/test_tools.py` calls the tool functions directly against the real Open-Meteo
API. `tests/test_server.py` launches the installed console script as a real MCP
stdio server and checks it advertises the right tools/resources/prompts over the
wire — both run in CI on every push with no API key required.

## Package layout

```
src/openmeteo_mcp/server.py   # FastMCP server: tools, resource, prompt
tests/                        # protocol- and tool-level tests, no LLM needed
client_stdio_test.py          # Agents SDK client demo (needs OPENAI_API_KEY)
client_sse_test.py            # same, over SSE
```