OpenWeatherMap MCP Server

English | 中文

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

1. Visit OpenWeatherMap
2. Register an account and get a free API key
3. 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:

{
  "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:

{
  "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

1. Direct Query: First attempts to query weather using the provided city name directly
2. Auto Fallback: If direct query fails (404 error), automatically triggers geocoding
3. Coordinate Conversion: Converts city name to precise coordinates via geocoding API
4. Re-query: Uses obtained coordinates to re-query weather data
5. 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

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

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

MIT License

🔗 Related Links

• OpenWeatherMap API Documentation
• Model Context Protocol
• Claude Desktop
• GitHub Repository