Skip to main content
Glama
README.md
# mcp-connector-example

A small, read-only MCP server for current weather and daily forecasts from Open-Meteo.

## What it does

Uses the official MCP Python SDK's FastMCP and httpx to query
https://api.open-meteo.com/v1/forecast. No API key, account, or secrets are needed.
Requests only read weather data; there are no write tools.

Coordinates use decimal degrees: latitude from -90 to 90 and longitude from
-180 to 180. Responses include the API's resolved coordinates, local timezone,
and units. Current conditions are model-based, not a live station observation.

## Quick start (under 5 minutes)

Use Python 3.10 or newer. From this directory:

```sh
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

On Windows, activate with `.venv\Scripts\activate` instead.

Add this entry to your Claude Desktop MCP configuration, replacing both
absolute paths with your local paths:

```json
{
  "mcpServers": {
    "weather": {
      "command": "/absolute/path/to/mcp-connector-example/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-connector-example/server.py"]
    }
  }
}
```

On Windows, use the virtual environment's `Scripts/python.exe` and absolute
Windows paths, escaping backslashes in JSON. Restart the client after saving.

Alternatively, register the same stdio server in Claude Code:

```sh
claude mcp add --transport stdio weather -- /absolute/path/to/mcp-connector-example/.venv/bin/python /absolute/path/to/mcp-connector-example/server.py
```

Ask the client for the weather at latitude `51.5`, longitude `-0.12`.
The client starts the server automatically. For a manual stdio launch, run
`python server.py`; it waits for MCP messages rather than presenting a prompt.

## Tools

- `get_forecast(latitude, longitude, days=3)` — accepts an integer from 1 to 7
  days, starting today in the location's timezone. Returns a `forecast` list
  with dates, maximum/minimum temperatures, precipitation totals, and weather
  codes, plus a `units` dictionary.
- `get_current(latitude, longitude)` — returns a `current` object containing
  the local timestamp, interval, temperature, relative humidity, apparent
  temperature, precipitation, weather code, and wind speed, plus a `units`
  dictionary.

Invalid arguments are rejected before any HTTP request. HTTP failures are
reported as tool errors. Weather codes follow Open-Meteo's WMO interpretation.

## Settings

The only application environment variable is `TIMEOUT_SECONDS`: an optional,
finite positive HTTP timeout in seconds, defaulting to `10`. Set it in the
server process's environment or its MCP configuration's `env` object.
The server reads the environment directly and does not load `.env` files.

## Tests

```sh
python -m pytest
```

Tests mock httpx; they make no network requests.

## Demo

![demo](docs/demo.gif)

GIF to be recorded

## Licence

MIT — see LICENSE. Copyright (c) 2026 japple12345.