OpenWeather MCP Server

An MCP server that exposes OpenWeather API data as tools for AI assistants. Built with FastMCP and Python.

Tools

Tool	Description
geocode	Convert a city name to geographic coordinates (lat/lon)
reverse_geocode	Convert coordinates to place names
get_current_weather	Current conditions — temp, humidity, wind, pressure, sunrise/sunset
get_forecast	1–5 day forecast with daily high/low, precipitation probability, conditions
get_air_quality	Air Quality Index (1–5), pollutant levels (PM2.5, O3, etc.), safety advisory

All tools accept city names with optional state/country disambiguation (e.g. "Portland, OR, US"). Weather and forecast tools support metric, imperial, and standard unit systems per request.

Prerequisites

• Python 3.12+
• uv
• An OpenWeather API key (free tier works)

Quick Start

# Install dependencies
uv sync

# Configure your API key
cp .env.example .env
# Edit .env and add your OpenWeather API key

# Start the server
uv run fastmcp run

Integration

Claude Code

Add to your Claude Code settings (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "openweather": {
      "command": "uv",
      "args": ["run", "fastmcp", "run"],
      "cwd": "/path/to/open-weather-mcp",
      "env": {
        "OPENWEATHER_API_KEY": "your_key_here"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "openweather": {
      "command": "uv",
      "args": ["run", "fastmcp", "run"],
      "cwd": "/path/to/open-weather-mcp",
      "env": {
        "OPENWEATHER_API_KEY": "your_key_here"
      }
    }
  }
}

Example Usage

Once connected to an MCP client, you can ask things like:

• "What's the weather in Tokyo?"
• "Give me a 3-day forecast for Denver in imperial units"
• "How's the air quality in Los Angeles?"
• "What are the coordinates for Paris, France?"

Development

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

Project Structure

src/open_weather_mcp/
├── server.py            # FastMCP server entry point
├── config.py            # .env loading, API key retrieval
├── client.py            # Shared async HTTP client
└── tools/
    ├── geocoding.py     # geocode, reverse_geocode
    ├── weather.py       # get_current_weather
    ├── forecast.py      # get_forecast
    └── air_quality.py   # get_air_quality

tests/
├── conftest.py          # Shared fixtures (mock HTTP, fake API key)
├── test_geocoding.py    # 15 tests
├── test_weather.py      # 18 tests
├── test_forecast.py     # 21 tests
└── test_air_quality.py  # 19 tests

73 tests total, all using mocked HTTP responses (no API calls during testing).

Tech Stack

• FastMCP — MCP server framework
• httpx — Async HTTP client
• python-dotenv — Environment variable loading
• uv — Package management
• pytest + pytest-asyncio — Testing
• ruff — Linting

License

MIT