Weather MCP Server (OpenWeather API)

A Model Context Protocol (MCP) server built with Python and uv that provides weather information by city name using the OpenWeather API (https://api.openweathermap.org/data/2.5/weather).

Table of Contents

• Features

• Prerequisites

• Step-by-Step Setup Guide

  • Step 1: Clone / Navigate to Project Directory

  • Step 2: Environment Configuration

  • Step 3: Install Dependencies

  • Step 4: Run the MCP Server

  • Step 5: Test Interactively with MCP Inspector

  • Step 6: Run Automated Tests

• MCP Tools Reference

• MCP Client Integration

• Project Structure

Related MCP server: Weather MCP Server

Features

• Get Weather by City Name: Fetches real-time weather metrics for any city (e.g., London, Chennai, New York,US).

• Structured JSON Output: Returns temperature (°C), feels-like (°C), humidity (%), pressure (hPa), weather conditions, and wind speed (m/s).

• Environment Key Integration: Loads OPENWEATHER_API_KEY automatically via .env / dotenv.

• Package Management via uv: Uses pyproject.toml and uv for reproducible builds.

Prerequisites

• Python: >= 3.10

• uv: Fast Python package manager (Installation Guide)

• Node.js & npx (Optional, for testing with MCP Inspector)

• OpenWeather API Key: Free key from OpenWeather SignUp

Step-by-Step Setup Guide

Step 1: Clone / Navigate to Project Directory

cd /Users/jayarajkannan/Learnings/project/mcp

Step 2: Environment Configuration

Create a .env file from .env.example and set your OpenWeather API key:

cp .env.example .env

Edit .env:

OPENWEATHER_API_KEY=your_actual_openweather_api_key_here

Step 3: Install Dependencies

Sync virtual environment and lockfile using uv:

uv sync

This installs mcp, httpx, and python-dotenv into the project environment.

Step 4: Run the MCP Server

You can run the server directly using uv:

uv run server.py

Or using the CLI script entry point defined in pyproject.toml:

uv run weather-mcp

Note: MCP servers communicate over stdio via JSON-RPC. Running the script directly will wait for input on stdin.

Step 5: Test Interactively with MCP Inspector

Use the official MCP Inspector to test and verify all tool calls in your browser UI:

npx @modelcontextprotocol/inspector uv run server.py

1. Open the URL printed in the terminal (e.g. http://127.0.0.1:6274?...).

2. Click Connect.

3. Select the get_weather tool.

4. Input a city name (e.g. London or Chennai) and click Run Tool.

Step 6: Run Automated Tests

Run the test suite using unittest and uv:

uv run python -m unittest test_server.py

MCP Tools Reference

get_weather

Gets current weather for a city using OpenWeather API.

Input Schema

Example Response Output

{
  "city": "London",
  "country": "GB",
  "temperature_c": 21.57,
  "feels_like_c": 21.58,
  "humidity": 69,
  "pressure": 1006,
  "weather": "Clouds",
  "description": "broken clouds",
  "wind_speed_mps": 9.26
}

MCP Client Integration

Add the Weather MCP server to your MCP client configuration (e.g. Claude Desktop claude_desktop_config.json or Antigravity .mcp.json):

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jayarajkannan/Learnings/project/mcp",
        "run",
        "server.py"
      ],
      "env": {
        "OPENWEATHER_API_KEY": "YOUR_OPENWEATHER_API_KEY"
      }
    }
  }
}

Project Structure

├── pyproject.toml    # Project dependencies and script entry points
├── uv.lock           # Locked dependency tree
├── server.py         # Weather MCP server implementation
├── test_server.py    # Automated unit tests
├── .env.example      # Sample environment configuration
├── .env              # Local environment variables (API Key)
└── README.md         # Documentation