Skip to content
Back to search

Weather-MCP-Server

A small Model Context Protocol (MCP) server, written in Python, that lets an AI assistant look up US weather forecasts and active weather alerts. It uses the free National Weather Service API and…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ad1singh--weather-mcp-server/badge.svg)](/listings/ad1singh--weather-mcp-server)

HTML

<a href="/listings/ad1singh--weather-mcp-server"><img src="/api/listings/ad1singh--weather-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

cd weather-mcp-server
uv sync

`uv sync` creates `.venv/` and installs everything listed in `pyproject.toml` and `uv.lock`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 146 lines
  1. # Weather MCP Server
  2. A small [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, written in Python, that lets an AI assistant look up US weather forecasts and active weather alerts. It uses the free [National Weather Service API](https://www.weather.gov/documentation/services-web-api) and talks to the AI client over stdio.
  3. **Limitation:** the National Weather Service only covers the United States (including territories). Requests for places outside the US return a clear error message.
  4. ## Tools
  5. | Tool | Input | What it returns |
  6. |---|---|---|
  7. | `get_forecast` | `latitude` (float, -90 to 90), `longitude` (float, -180 to 180) | The next five forecast periods: temperature, temperature unit, wind speed, wind direction, detailed forecast |
  8. | `get_alerts` | `state` (two-letter US code, for example `CA`; case does not matter) | Each active alert: event, area, severity, description, instructions. If there are none, it says so |
  9. Failures (bad input, network problem, timeout, unsupported location, unexpected API data) are reported to the client as tool errors (`isError: true`) with a readable message. The server itself does not crash.
  10. ## Requirements
  11. - Python 3.13
  12. - [uv](https://docs.astral.sh/uv/)
  13. - Node.js (only for MCP Inspector)
  14. ## Install
  15. ```bash
  16. cd weather-mcp-server
  17. uv sync
  18. ```
  19. `uv sync` creates `.venv/` and installs everything listed in `pyproject.toml` and `uv.lock`.
  20. ## Run
  21. ```bash
  22. uv run weather.py
  23. ```
  24. The server starts and silently waits for an MCP client to talk to it over stdin/stdout. Nothing else is printed; that is normal. Logs go to stderr. Press Ctrl+C to stop.
  25. ## Test
  26. Automated tests (no internet needed; HTTP is mocked):
  27. ```bash
  28. uv run pytest -v
  29. ```
  30. ### Try the real tools with MCP Inspector
  31. Inspector is an official tool for calling an MCP server by hand.
  32. Interactive web UI:
  33. ```bash
  34. npx @modelcontextprotocol/inspector uv run weather.py
  35. ```
  36. Open the URL it prints. Click **Connect**, open the **Tools** tab, click **List Tools** (you should see `get_forecast` and `get_alerts`), choose a tool, fill in the inputs, and click **Run Tool**.
  37. Good inputs to try:
  38. - `get_forecast` with latitude `38.8977`, longitude `-77.0365` (Washington, DC)
  39. - `get_alerts` with state `CA`
  40. - Bad inputs: latitude `999`, or state `C1`. You should get an error message, not a crash
  41. Command line version (good for scripts):
  42. ```bash
  43. npx @modelcontextprotocol/inspector --cli uv run weather.py --method tools/list
  44. npx @modelcontextprotocol/inspector --cli uv run weather.py --method tools/call \
  45. --tool-name get_alerts --tool-arg state=CA
  46. ```
  47. ## Connect to an MCP host (Claude Desktop)
  48. Open the Claude Desktop config file:
  49. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  50. - Linux: `~/.config/Claude/claude_desktop_config.json`
  51. - Windows: `%AppData%\Claude\claude_desktop_config.json`
  52. Add the server (use the absolute path to this folder; on Windows use `\\` or `/` in the path):
  53. ```json
  54. {
  55. "mcpServers": {
  56. "weather": {
  57. "command": "uv",
  58. "args": [
  59. "--directory",
  60. "/ABSOLUTE/PATH/TO/weather-mcp-server",
  61. "run",
  62. "weather.py"
  63. ]
  64. }
  65. }
  66. }
  67. ```
  68. Save the file and restart Claude Desktop. If it cannot find `uv`, put the full path in `command` (run `which uv` on macOS/Linux or `where uv` on Windows).
  69. ## How it works
  70. ```
  71. weather-mcp-server/
  72. ├── weather.py the whole server
  73. ├── pyproject.toml project metadata and dependencies
  74. ├── uv.lock exact locked versions (commit this)
  75. ├── tests/
  76. │ └── test_weather.py automated tests
  77. └── README.md
  78. ```
  79. Inside `weather.py`, top to bottom:
  80. 1. **Logging setup.** Python's standard `logging`, pointed at stderr. stdout is the MCP message channel, so printing to it would corrupt the protocol. Never use `print()` in this server.
  81. 2. **`MCPServer("weather")`.** The server object from the official SDK (v2). It reads each tool function's type hints and docstring and builds the tool description the AI client sees.
  82. 3. **Validation functions.** `validate_coordinates` and `normalize_state` are plain functions with no network calls, so they are quick to test. They run before any request is made.
  83. 4. **`make_nws_request`.** One reusable async helper for every API call. It sends a `User-Agent` (NWS asks for one), uses a 20 second timeout, and turns every failure (timeout, connection error, HTTP error, invalid JSON, unexpected shape) into a result with an error message instead of an exception.
  84. 5. **`get_forecast`.** Calls `/points/{lat},{lon}`, reads the forecast URL from the answer, fetches that URL, and formats the first five periods. Coordinates are rounded to four decimals because NWS redirects longer ones.
  85. 6. **`get_alerts`.** Calls `/alerts/active/area/{STATE}` and formats each alert. An empty list is a normal result: "No active weather alerts for CA."
  86. 7. **`mcp.run(transport="stdio")`.** Starts the server and keeps it listening.
  87. `@mcp.tool()` is a decorator that registers a function as an MCP tool. `async def` means the function can wait on the network without blocking the server.
  88. ### Dependencies
  89. - `mcp[cli]>=2,<3`: the official MCP Python SDK, version 2.
  90. - `httpx2`: the HTTP client. SDK v2 depends on `httpx2` and no longer installs the older `httpx` package, so this project imports `httpx2` directly and lists it explicitly.
  91. - Dev only: `pytest`, `pytest-asyncio`.
  92. Note for v1 users: v1's `FastMCP` class (`mcp.server.fastmcp`) no longer exists. v2 uses `MCPServer` (`mcp.server.mcpserver`).
  93. ## Troubleshooting
  94. | Problem | Likely cause and fix |
  95. |---|---|
  96. | Server seems to hang after `uv run weather.py` | Normal. It is waiting for an MCP client. |
  97. | Client shows garbled or broken protocol errors | Something wrote to stdout. Remove any `print()`; use `logger` instead. |
  98. | Claude Desktop does not show the tools | Check the path in the config is absolute and correct, use the full path to `uv`, then fully restart Claude Desktop. |
  99. | `ModuleNotFoundError: mcp.server.fastmcp` | v1 import in v2 code. Use `from mcp.server.mcpserver import MCPServer`. |
  100. | `ModuleNotFoundError: httpx` | v2 no longer installs it. Use `httpx2`. |
  101. | "Could not connect to the weather service" | No internet, or a proxy or firewall is blocking `api.weather.gov`. |
  102. | "weather service timed out" | NWS is slow or down. Try again in a moment. |
  103. | "No forecast available for this location" | The point is outside NWS coverage (not in the US). |
  104. | "HTTP 5xx" errors | The NWS API is having problems. Try again later. |
  105. | Tests fail on import | Run them from the project folder with `uv run pytest`. |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.