# mcp-server-weatheo

An MCP (Model Context Protocol) server that gives AI assistants live weather for any city covered by [weatheo.com](https://weatheo.com): current conditions, an hourly forecast (24 h), a daily forecast (14 days) and an air-quality index. It can also produce a ready-made weather badge snippet (Markdown and HTML) for a README or web page. No API key is needed.

The server speaks MCP over stdio and needs Node.js 18 or newer.

## Install

The server is run with `npx` straight from GitHub.

### Claude Desktop

Add this to `claude_desktop_config.json` (Settings, Developer, Edit Config) and restart Claude Desktop:

```json
{
  "mcpServers": {
    "weatheo": {
      "command": "npx",
      "args": ["-y", "github:weatheo-com/mcp-server-weatheo"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add weatheo -- npx -y github:weatheo-com/mcp-server-weatheo
```

### Cursor

Add the same object to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for all projects):

```json
{
  "mcpServers": {
    "weatheo": {
      "command": "npx",
      "args": ["-y", "github:weatheo-com/mcp-server-weatheo"]
    }
  }
}
```

## Tools

| Tool | Arguments | Description |
| --- | --- | --- |
| `search_places` | `query` (string, 2-80 characters, required), `lang` (optional) | Searches cities and towns, returns up to 10 matches with their place keys. |
| `get_weather` | `place` (key `country/region/city`, required), `lang`, `units`, `include` (array of `current`, `hourly`, `daily`, `aqi`; default `["current", "daily"]`) | Forecast data for one place. |
| `get_weather_badge` | `place` (required), `style` (`line` default, or `card`), `theme` (`light` default, or `dark`), `lang`, `units` | Embeddable SVG weather badge: a Markdown snippet and the HTML equivalent. |

Shared arguments: `lang` is one of `en` (default), `fr`, `de`, `zh`, `zh-hant`, `es`, `it`, `pt`, `ja`, `ko`, `ru`, `ar`; `units` is `metric` (default, degrees C and km/h) or `imperial` (degrees F and mph). Place keys come from `search_places`.

The results below were produced by running the server against the mock API used by `npm test` (the daily list is shortened there).

### search_places

```json
{ "query": "gien" }
```

```text
1. Gien — Centre-Val de Loire, France — key: fr/centre-val-de-loire/gien — https://weatheo.com/fr/fr/centre-val-de-loire/gien
2. Saint-Gondon — Centre-Val de Loire, France — key: fr/centre-val-de-loire/saint-gondon — https://weatheo.com/fr/fr/centre-val-de-loire/saint-gondon

Source: https://weatheo.com
```

### get_weather

```json
{ "place": "fr/centre-val-de-loire/gien" }
```

```text
Weather for Gien, Loiret, Centre-Val de Loire, France (key: fr/centre-val-de-loire/gien; 47.6897, 2.6305; time zone Europe/Paris)
Updated: 2026-11-13T09:00:00Z

Current conditions:
  Broken clouds, 8°C (feels like 6°C)
  Humidity 87%, wind 14 km/h, precipitation probability 20%

Daily forecast:
  Fri 2026-11-13  4°C / 11°C, Clear sky, rain 30%
  Sat 2026-11-14  5°C / 12°C, Clear sky, rain 30%

Source: https://weatheo.com/fr/fr/centre-val-de-loire/gien
```

The tool also returns the selected blocks as structured content.

### get_weather_badge

```json
{ "place": "fr/centre-val-de-loire/gien", "style": "card", "theme": "dark" }
```

```text
[![Weather in Gien](https://weatheo.com/badge/fr/centre-val-de-loire/gien.svg?style=card&theme=dark)](https://weatheo.com/fr/fr/centre-val-de-loire/gien)

HTML:
<a href="https://weatheo.com/fr/fr/centre-val-de-loire/gien"><img src="https://weatheo.com/badge/fr/centre-val-de-loire/gien.svg?style=card&amp;theme=dark" alt="Weather in Gien"></a>

Source: https://weatheo.com/fr/fr/centre-val-de-loire/gien
```

(In the test run the image host is the mock server; with the default configuration it is `https://weatheo.com`, as shown.)

Errors (unknown place, bad arguments, service unavailable, network failure) come back as tool errors with a plain message; an unknown place points the assistant to `search_places`.

## Example prompts

- What is the weather in Gien this weekend?
- Compare tomorrow in Lyon and Lille.
- Give me a weather badge for my README for Annecy.

## Configuration

| Variable | Default | Description |
| --- | --- | --- |
| `WEATHEO_BASE_URL` | `https://weatheo.com` | Base URL of the weatheo.com API. |

Requires Node.js 18 or newer. Requests time out after 10 seconds.

## Data and attribution

Forecasts come from the weatheo.com public API, for example `https://weatheo.com/api/v1/weather?place=fr/centre-val-de-loire/gien`. Every answer ends with a `Source:` line with the URL of the city page on weatheo.com. The air-quality value is a US-EPA-style index, not the European AQI. Methodology: https://weatheo.com/en/blog/methodology

## Related

- https://github.com/weatheo-com/github-readme-weather
- https://github.com/weatheo-com/weatheo-ui
- https://github.com/weatheo-com/climate-data

## Development

```bash
npm install
npm test
```

`npm test` starts a mock weatheo API and drives the server with a real stdio MCP client.

## Publishing (maintainers only)

Precondition: the MCP Registry hosts metadata only, so the npm package `mcp-server-weatheo` must be published on npm before the registry accepts `server.json`. The registry checks that the published package's `mcpName` in `package.json` equals the `name` in `server.json` (`io.github.weatheo-com/mcp-server-weatheo`), and with GitHub authentication the name must start with `io.github.<github-user-or-org>/`. `version` in `server.json` (top level and in `packages`) must match the published npm version. The `description` is limited to 100 characters.

Steps, once the above holds: `npm publish`, then `mcp-publisher login github` and `mcp-publisher publish` in this directory (see the registry quickstart: https://github.com/modelcontextprotocol/registry). None of this has been done yet.

## Licence

MIT, see [LICENSE](LICENSE).