weather-mcp

A minimal Model Context Protocol server in a single file. It speaks JSON-RPC 2.0 over stdio and exposes two tools, get_weather and get_hourly_forecast, backed by the free Open-Meteo API.

No third-party runtime dependencies — standard library only. Requires Python 3.8+.

Quick start: Claude Code

1. Prepare your terminal

Open Terminal on macOS/Linux or PowerShell on Windows. Paste the command blocks in this guide there. Weather questions and commands beginning with /, such as /login and /mcp, belong inside a Claude Code conversation. If Claude Code is already open in your terminal, use a new terminal tab for setup.

1. Install Claude Code using its official setup guide. Run claude --version in your terminal to check that it is available. Then run claude and follow the sign-in prompts; if needed, type /login inside Claude Code. Keep a separate terminal tab open for the next steps.
2. Install uv using the instructions for your operating system. uv supplies uvx, which downloads and runs the weather package for you. Reopen your terminal after installation and run uvx --version. If either version check says “command not found,” finish that installation before continuing.

You need an internet connection to download the package and fetch weather. No weather API key is needed.

2. Add the weather server

Run this in your terminal:

claude mcp add --scope user weather -- uvx myai-weather-mcp==0.1.2

weather is the name you will see in Claude Code. myai-weather-mcp is the published package it runs. User scope makes this setup available across your Claude Code projects. No repository clone or separate package installation is needed. See the Claude Code MCP reference for other setup options.

The ==0.1.2 pin selects the release used in this guide, so a later release does not silently change your setup. It is intentional; see Updating your version when you want to upgrade.

If weather already exists, inspect it with claude mcp get weather. If it already uses the command above, continue to the next step. To replace an older user-scope setup, follow the replacement steps under Updating your version.

3. Check the connection and ask for weather

Run in your terminal:

claude mcp get weather

Look for Connected. If you see a different status or no server is found, use Connection troubleshooting below.

Start a new Claude Code session by running claude, or type /mcp inside an existing session and reconnect weather. At Claude Code's conversation prompt, paste:

• “Use the weather tool to tell me the current weather in Tokyo.”
• “Use the hourly forecast tool to show the next six hours in Tokyo.”

Expect current conditions, temperature in °F, wind in mph, and six forecast rows with local times and rain probabilities. Values change with the weather.

Updating your version

Check the release notes and choose a published version. To replace the user-scope registration, first inspect claude mcp get weather and save any custom settings you want to keep. Then run the following commands, replacing 0.1.2 with your chosen version in the add command:

claude mcp remove --scope user weather
claude mcp add --scope user weather -- uvx myai-weather-mcp==0.1.2
claude mcp get weather

Removing the registration removes that client configuration, not your repository or source files. If your existing registration is in local or project scope, inspect that configuration before changing it; a same-name entry there may override the user-scope entry.

Reconnect through /mcp or start a new Claude Code session after replacing it. For Claude Desktop, change the version in its configuration's args and restart.

Refreshing uv's cache does not change a saved version pin. If a version that is already published cannot be found, run the following with the version you selected:

uvx --refresh myai-weather-mcp==0.1.2

If the terminal stays blank without an error, the server is waiting for a client; press Control+C, then reconnect your client. See uv's tool guide for more about running tools and selecting versions.

Connection troubleshooting

• No server named weather: run the add command in step 2, then check again.
• Failed to connect or another non-connected status: inspect the command and arguments printed by claude mcp get weather. Try uvx myai-weather-mcp==0.1.2 directly in your terminal and read any error. If it starts without an error and waits, press Control+C and reconnect through /mcp. A successful start checks that the package can launch; ask for weather to check the network too.
• uvx not found: install uv and reopen your terminal. If the terminal finds it but your client does not, find its full path with command -v uvx (macOS/Linux) or where.exe uvx (Windows PowerShell). Use that path in place of uvx in the registration or configuration; quote paths containing spaces.
• Package download fails: check your internet connection and the exact package name and version. If the selected release exists but uv cannot find it, use the cache-refresh command above. For UnknownIssuer, see the certificate-error steps below.
• Connected, but tools are missing: start a new Claude Code session or use /mcp to check whether weather is enabled and reconnect it.
• A blank terminal after starting the server directly: it is waiting for an MCP client. This is expected; press Control+C and use the client setup above.
• Claude Code says “Not logged in”: open claude and run /login.
• Connected, but weather requests fail: check the returned error and your internet connection. The server must reach Open-Meteo to retrieve weather.
• Location not found: try a well-known city name. An unknown place should return a readable error rather than a forecast.

PyPI certificate error (UnknownIssuer)

If the terminal shows invalid peer certificate: UnknownIssuer while uvx fetches from pypi.org, the package launcher cannot verify that HTTPS connection. This happens before the weather server starts and may appear in your client as Connection closed during initialization. Other connection errors can have different causes.

Try using the certificates already trusted by your operating system:

uvx --system-certs myai-weather-mcp==0.1.2

This can help on a managed network whose certificate is in the system trust store. It keeps certificate verification enabled. If the server starts and waits without an error, press Control+C. To use the same option in Claude Code, follow the registration replacement steps, using this add command:

claude mcp add --scope user weather -- uvx --system-certs myai-weather-mcp==0.1.2

For Claude Desktop's uvx setup, change args to ["--system-certs", "myai-weather-mcp==0.1.2"]. Reconnect or restart your client, then ask for weather to check the full connection. Use your selected package version if it differs from this guide's pin.

If uvx does not recognize the flag, update uv using its installation method. If certificate verification still fails, consult your network administrator and uv's certificate documentation. Keep verification enabled; do not use --allow-insecure-host to bypass the error. If your existing setup works, no configuration change is needed.

Help us test

Try the two questions above and a made-up location such as ZzzxqqNowhere. If anything is confusing, open an issue with your operating system, client, package version, steps, and the error message. Remove passwords, authentication codes, and other private information before sharing.

The tools

Usage

The responses below are illustrative snapshots, not current weather.

Once the server is wired into a client, just ask in natural language — the model picks the tool and fills in the arguments:

You: What's the weather in Seattle right now?

Claude: (calls get_weather with location: "Seattle") Current weather in Seattle, United States: overcast, 54.2 °F, wind 1.1 mph.

You: Will it rain in Tokyo over the next 6 hours?

Claude: (calls get_hourly_forecast with location: "Tokyo", hours: 6) Yes — drizzle every hour, precipitation probability climbing from 76 % to 89 %.

Try it without a client