Weather MCP Server 🌦️

A from-scratch Model Context Protocol (MCP) server that gives Claude Desktop (or any MCP host) live weather data. It wraps the free Open-Meteo API (no API key required), keeps a small SQLite-backed list of favorite cities, and can optionally push weather to a Telegram bot.

• Language / SDK: Python 3.10+ with the official mcp package (FastMCP high-level API)
• Transport: stdio
• Weather API: Open-Meteo (geocoding + forecast) — keyless, free
• Storage: local SQLite file (favorites.db)

---

Capabilities

🛠 Tools

| Tool | Arguments | Kind | Description | |------|-----------|------|-------------| | get_current_weather | city (required) | live API | Current conditions for a city: temperature, feels-like, humidity, precipitation, wind, sky condition. | | get_forecast | city (required), days (optional, default 3, 1–16) | live API | Multi-day forecast: per-day min/max temperature, precipitation sum, max wind, sky condition. | | add_favorite_city | city (required) | write → SQLite | Geocodes a city and saves it to the favorites list (deduplicated). | | remove_favorite_city | city (required) | write → SQLite | Removes a city from favorites (case-insensitive, with a geocoding fallback). | | send_telegram_message | text (required) | outbound API | Sends an arbitrary text message to a Telegram chat. (optional — needs .env) | | send_weather_to_telegram | city (required) | live + outbound | Fetches current weather and pushes it to a Telegram chat in one step. (optional — needs .env) |

📄 Resource

| Resource URI | Returns | Logic | |--------------|---------|-------| | weather://favorites | Markdown list of saved cities (name, country, coordinates, when added) | Reads live from the SQLite database on every read — not a stub. |

All weather is fetched live on every call (no hard-coded responses), and the resource always reflects the real, current contents of the database.

Note on resources vs. tools: an MCP host calls tools automatically, but a resource is content you attach to the conversation. In Claude Desktop, open + → <weather> → Add from weather → Favorites resource to load the current favorites into context.

---

Requirements

• Python 3.10+
• The dependencies in requirements.txt (mcp[cli], httpx, python-dotenv)
• An MCP host such as Claude Desktop (optional — you can also test with the MCP Inspector)

---

Setup

1. Clone & create a virtual environment

git clone https://github.com/<your-user>/<repo>.git
cd <repo>
python -m venv .venv
.\.venv\Scripts\Activate.ps1          # Windows PowerShell
# source .venv/bin/activate           # macOS / Linux

2. Install dependencies

pip install -r requirements.txt

3. (Optional) Try it locally with the MCP Inspector

The Inspector speaks the same JSON-RPC/stdio protocol and gives you a UI to list tools, call them, and read resources — the fastest way to verify the server before wiring it into a host.

mcp dev server.py

Open the printed http://localhost:... URL, click List Tools, call get_current_weather with {"city": "Kyiv"}, and read the weather://favorites resource.

---

Connect to Claude Desktop

1. Open (or create) the Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

(for the Microsoft Store build it lives under %LOCALAPPDATA%\Packages\Claude_\LocalCache\Roaming\Claude\)*

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

1. Add a weather server entry with absolute paths to the venv's Python and

to server.py (see claude_desktop_config.json for a ready example):

   {
     "mcpServers": {
       "weather": {
         "command": "C:\\path\\to\\mcp\\.venv\\Scripts\\python.exe",
         "args": ["C:\\path\\to\\mcp\\server.py"]
       }
     }
   }

On Windows, escape backslashes (\\) in JSON. The venv Python is used so that mcp and httpx are on the path; no cwd is needed because the database path is resolved relative to server.py.

1. Fully quit and restart Claude Desktop. The weather server should appear

in the tools menu (🔌 / hammer icon), and you can ask Claude about the weather.

ℹ️ The claude_desktop_config.json in this repository is a template/example only. Claude Desktop reads the file in the system location from step 1 — not the copy in the project folder. Copy the mcpServers block into that system file (or merge it if the file already exists).

---

Telegram integration (optional)

The send_telegram_message and send_weather_to_telegram tools forward weather to a Telegram bot. They stay disabled until credentials are provided, so the server runs fine without this step.

1. Create a bot: message @BotFather, send /newbot,

and copy the bot token.

1. Find your chat id: message @userinfobot (it

replies with your numeric id), or open https://api.telegram.org/bot<token>/getUpdates after messaging your bot.

1. Create .env next to server.py (copy from .env.example):

   TELEGRAM_BOT_TOKEN=123456789:AA-your-real-token
   TELEGRAM_CHAT_ID=123456789

1. Restart Claude Desktop, then ask: *"Send the current weather in Kyiv to my

Telegram."* The message is delivered in Ukrainian.

🔒 .env is listed in .gitignore and is never committed — the token stays only on your machine.

---

Example dialogs

The assistant replies in the user's language; the prompts below match the screenshots in examples/.

1. Current weather — required argument

You:    Яка зараз погода в Києві?
Claude: → get_current_weather(city="Kyiv")
        Зараз у Києві ☁️ хмарно, +22.7 °C (відчувається як +23.4 °C),
        вологість 58 %, вітер слабкий — 3.6 км/год, без опадів.

2. Forecast — optional days argument

You:    Який прогноз погоди у Львові на найближчі 5 днів?
Claude: → get_forecast(city="Lviv", days=5)
        • 21.06 — ☁️ хмарно, +20…+31 °C
        • 22.06 — 🌧️ помірний дощ, +21…+30 °C, опади 4.9 мм
        • ...

3. Favorites + resource

You:    Додай Київ і Львів у мої улюблені, потім прибери Львів.
Claude: → add_favorite_city("Kyiv") → add_favorite_city("Lviv")
        → remove_favorite_city("Lviv")
        Готово. (Attach "Favorites resource" to see the live list: Київ.)

4. Weather → Telegram (optional)

You:    Скинь мені поточну погоду в Києві в Telegram.
Claude: → send_weather_to_telegram(city="Kyiv")
        Готово — повідомлення відправлено у твій Telegram-чат. ✅

Screenshots of these conversations are in examples/.

---

Project structure

mcp/
├── server.py                   # the MCP server (tools + resource)
├── requirements.txt            # pinned dependencies
├── claude_desktop_config.json  # example host config
├── .env.example                # template for Telegram secrets
├── README.md
├── examples/                   # screenshots of Claude Desktop dialogs
├── .env                        # your Telegram secrets (git-ignored, optional)
└── favorites.db                # created at runtime (git-ignored)

---

Known limitations

• City disambiguation is naive. The geocoder takes the top match for a

name. Ambiguous names (e.g. "Springfield") may resolve to the wrong place; the tools surface the resolved City, Region, Country so it is visible.

• Forecast horizon. days is clamped to Open-Meteo's supported range (1–16);

out-of-range values are clamped, not rejected.

• Network-dependent. Every weather call hits Open-Meteo live; offline or

rate-limited requests fail with an error surfaced back to the host.

• No caching. Repeated identical questions re-fetch from the API.
• favorites.db is local and unencrypted. It only stores public city

coordinates and is not synced or backed up.

• Telegram is optional and single-chat. The send_* tools target one

pre-configured TELEGRAM_CHAT_ID; no per-message recipient, no retry, no rate limiting. Without .env they fail with a clear "not configured" message.

• stdio only. No HTTP/SSE transport and no authentication — intended for a

local, single-user host, not a shared/remote deployment.

Security notes

• The server writes only JSON-RPC to stdout; all diagnostics go to

stderr, as the stdio transport requires.

• No shell execution and no string interpolation into commands → no command

injection surface.

• API arguments are passed as typed query parameters via httpx, never

concatenated into URLs by hand.

• The only secret (the Telegram token) lives in .env, which is git-ignored; the

weather API itself is keyless.

---

Credits

• Weather & geocoding data: Open-Meteo (CC BY 4.0).
• Protocol: Model Context Protocol.