OpenWeatherMap MCP Server

A comprehensive OpenWeatherMap API integration server based on Model Context Protocol (MCP), providing AI assistants with full weather data access capabilities.

🌟 Key Features

Core Weather Functions

🌡️ Current Weather Query - Real-time weather data including temperature, humidity, wind speed, pressure, etc.
📅 Weather Forecast - 5-day/3-hour interval detailed weather forecasts with trend analysis
🏭 Air Quality Monitoring - Real-time air quality index and pollutant concentration data
🗺️ Weather Maps - Multi-layer weather map tiles (clouds, precipitation, temperature, etc.)
⚠️ Weather Alerts - Government-issued weather warnings and safety advisories
📊 Historical Weather - Historical weather data queries and multi-day comparison analysis

Smart City Name Query

🧠 Intelligent Fallback - Automatically handles both Chinese and English city names
🔄 Auto-Geocoding - When direct city name query fails, automatically uses geocoding to get coordinates
🌍 Universal Support - Works with city names in any language through geocoding API

Additional Features

🌍 Geocoding - Place name to coordinates conversion with fuzzy search support
📍 Reverse Geocoding - Coordinates to place name conversion
🔄 Multi-Unit Support - Metric, Imperial, and Standard unit systems
🌐 Multi-Language Support - Chinese, English, and many other languages

📦 Installation

Prerequisites

Node.js 18.0.0 or higher
OpenWeatherMap API key

Get API Key

Visit OpenWeatherMap
Register an account and get a free API key
Set environment variable:

   export OPENWEATHER_API_KEY="your_api_key_here"

Installation Methods

Method 1: NPM Global Installation

npm install -g openweather-mcp

Method 2: Build from Source

git clone https://github.com/QianJue-CN/OpenWeatherMCP.git
cd OpenWeatherMCP
npm install
npm run build

🚀 Usage

Run as MCP Server

# Set API key
export OPENWEATHER_API_KEY="your_api_key_here"

# Start server
npx openweather-mcp

Configure in Claude Desktop

Add to Claude Desktop configuration file:

{
  "mcpServers": {
    "openweather": {
      "command": "npx",
      "args": ["openweather-mcp"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

Use with Other MCP Clients

Any MCP protocol-compatible client can connect to this server.

🛠️ Available Tools

1. Current Weather Query (`get_current_weather`)

Get real-time weather information for specified location.

Parameters:

city (optional): City name, e.g., "Beijing" or "北京" or "Beijing,CN"
lat (optional): Latitude (-90 to 90)
lon (optional): Longitude (-180 to 180)
zip (optional): Postal code, e.g., "10001,US"
units (optional): Unit system (metric/imperial/standard)
lang (optional): Language code (zh_cn/en/es/fr/de/ja/ko/ru)

Smart City Name Support:

✅ "北京" (Chinese) → Automatically works
✅ "Beijing" (English) → Automatically works
✅ "上海" (Chinese) → Automatically works
✅ "Shanghai" (English) → Automatically works

Example: ``json { "city": "北京", "units": "metric", "lang": "zh_cn" } ``

2. Weather Forecast (`get_weather_forecast`)

Get 5-day weather forecast data.

Parameters:

Location parameters same as above
cnt (optional): Number of forecast time points (max 40)

Example: ``json { "lat": 39.9042, "lon": 116.4074, "cnt": 16, "units": "metric" } ``

3. Air Quality (`get_air_quality`)

Get air quality data.

Parameters:

lat: Latitude
lon: Longitude
start (optional): Start timestamp (for historical data)
end (optional): End timestamp (for historical data)

4. Weather Maps (`get_weather_map`)

Get weather map tiles.

Parameters:

layer: Layer type (clouds_new/precipitation_new/pressure_new/wind_new/temp_new)
z: Zoom level (0-10)
x: Tile X coordinate
y: Tile Y coordinate

5. Weather Alerts (`get_weather_alerts`)

Get weather warning information.

Parameters:

lat: Latitude
lon: Longitude

6. Historical Weather (`get_historical_weather`)

Query historical weather data.

Parameters:

lat: Latitude
lon: Longitude
dt: Unix timestamp for query date
units: Unit system
lang: Language code

7. Geocoding (`geocoding`)

Get coordinates from place names.

Parameters:

q: Location query string
limit: Number of results to return (1-5)

8. Reverse Geocoding (`reverse_geocoding`)

Get place names from coordinates.

Parameters:

lat: Latitude
lon: Longitude
limit: Number of results to return (1-5)

📝 Usage Examples

Query Beijing Current Weather

{
  "tool": "get_current_weather",
  "parameters": {
    "city": "北京",
    "units": "metric",
    "lang": "zh_cn"
  }
}

Get Shanghai 5-Day Weather Forecast

{
  "tool": "get_weather_forecast",
  "parameters": {
    "city": "上海",
    "units": "metric",
    "lang": "zh_cn"
  }
}

Query Air Quality

{
  "tool": "get_air_quality",
  "parameters": {
    "lat": 39.9042,
    "lon": 116.4074
  }
}

🌍 How Smart City Name Query Works

Direct Query: First attempts to query weather using the provided city name directly
Auto Fallback: If direct query fails (404 error), automatically triggers geocoding
Coordinate Conversion: Converts city name to precise coordinates via geocoding API
Re-query: Uses obtained coordinates to re-query weather data
Seamless Experience: The entire process is transparent to users, no manual handling required

This means you can use city names in any language:

Chinese: 北京、上海、广州、深圳
English: Beijing, Shanghai, Guangzhou, Shenzhen
Other languages: 東京、ソウル、Paris, London

🔧 Development

Project Structure

src/
├── index.ts              # MCP server entry point
├── types/
│   ├── weather.ts        # Weather data type definitions
│   └── mcp.ts           # MCP tool type definitions
├── services/
│   └── openweather.ts   # OpenWeatherMap API service
└── tools/
    ├── current-weather.ts    # Current weather tool
    ├── forecast.ts          # Weather forecast tool
    ├── air-pollution.ts     # Air quality tool
    ├── weather-maps.ts      # Weather maps tool
    ├── weather-alerts.ts    # Weather alerts tool
    └── historical-weather.ts # Historical weather tool

Build and Test

# Install dependencies
npm install

# Build project
npm run build

# Development mode (watch file changes)
npm run dev

# Run tests
npm test

# Code linting
npm run lint

🌍 Supported Location Formats

City Names

"北京" - Chinese city name
"Beijing" - English city name
"Beijing,CN" - City name + country code
"New York,US" - Full format

Coordinates

Latitude: -90 to 90
Longitude: -180 to 180
Example: lat: 39.9042, lon: 116.4074

Postal Codes

"10001,US" - US postal code
"100000,CN" - Chinese postal code

📊 Data Formats

Temperature Units

metric: Celsius (°C)
imperial: Fahrenheit (°F)
standard: Kelvin (K)

Wind Speed Units

metric: Meters per second (m/s)
imperial: Miles per hour (mph)

Language Support

zh_cn: Simplified Chinese
en: English
es: Spanish
fr: French
de: German
ja: Japanese
ko: Korean
ru: Russian

⚠️ Important Notes

API Limits: Free accounts have call limits, please use reasonably
Historical Data: Historical weather data requires paid subscription
One Call API: Weather alerts feature requires One Call API 3.0 subscription
Network Connection: Ensure server can access OpenWeatherMap API

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

MIT License

OpenWeatherMap MCP Server