⛅ Weather MCP Server

A lightweight MCP (Model Context Protocol) server that exposes a single tool — real-time weather lookup for any location — to any MCP-compatible client, such as Claude Desktop.

---

🧠 How It Works

1. A FastMCP server named "Weather Checker" is started over stdio transport.
2. It exposes one async tool, check_weather(location: str), callable by any connected MCP client.
3. Internally, the tool calls get_weather(), which hits wttr.in — a free, no-auth-required weather service — and returns a concise, one-line weather summary for the given location.
4. No API keys, no sign-ups, no external dependencies beyond the mcp package itself.

---

🗂️ Project Structure

├── main.py                 # MCP server entry point — defines and runs the check_weather tool
├── tools/
│   ├── __init__.py
│   └── weather.py          # Fetches weather data from wttr.in
├── pyproject.toml          # Project metadata and dependencies (uv-managed)
├── requrements.txt          # Pip-installable dependencies
├── uv.lock                  # Locked dependency versions
└── .python-version          # Python 3.13

---

🛠️ Tech Stack

Layer	Technology
Protocol	MCP (Model Context Protocol) — FastMCP, stdio transport
Weather Data Source	wttr.in — free console-friendly weather API
HTTP Client	Python standard library (urllib.request)
Package Management	uv
Language	Python 3.13

---

⚙️ Local Setup

1. Clone the Repository

git clone https://github.com/<your-username>/<repo-name>.git
cd <repo-name>

2. Install Dependencies

Using uv (recommended, matches uv.lock):

uv sync

Or using standard venv + pip:

python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
pip install -e .

3. Run the Server

python main.py

The server starts and communicates over stdio — it's designed to be launched by an MCP client, not accessed directly via a browser or REST call.

---

🔌 Connecting to an MCP Client

To use this server with an MCP-compatible client (e.g. Claude Desktop), add it to the client's MCP server configuration:

{
  "mcpServers": {
    "weather-checker": {
      "command": "python",
      "args": ["main.py"]
    }
  }
}

If using uv:

{
  "mcpServers": {
    "weather-checker": {
      "command": "uv",
      "args": ["run", "main.py"]
    }
  }
}

Once connected, the client can call the check_weather tool directly — for example, asking "What's the weather in London?" will invoke check_weather(location="London") behind the scenes.

---

🔧 Available Tools

Tool	Parameters	Returns	Description
check_weather	location: str (e.g. "New York", "London")	Concise weather summary (string)	Fetches current weather conditions for the specified location via wttr.in

Example Output

New York: ☀️   +24°C

---

📌 Key Features

• ✅ Zero-configuration — no API keys or environment variables required
• ✅ Minimal dependency footprint (mcp[cli] only)
• ✅ Clean separation between MCP tool definition (main.py) and the underlying data-fetch logic (tools/weather.py)
• ✅ Graceful error handling — returns a readable error string instead of raising on failed requests
• ✅ Async tool definition, ready to scale to additional tools in the same server

---

📄 License

This project is for educational purposes.