🌤️ MCP Weather Server / 全球天气MCP服务器

A powerful Model Context Protocol (MCP) server that provides global weather information with special support for Chinese cities. Perfect for AI assistants like Claude to access real-time weather data.

一个强大的模型上下文协议(MCP)服务器，提供全球天气信息，特别优化了对中国城市的支持。

✨ Features / 功能特性

🌍 Global Weather Support / 全球天气支持

• Current Weather - Real-time weather for any city worldwide / 全球任意城市的实时天气
• 5-Day Forecast - Detailed weather forecasts / 详细的5天天气预报
• Chinese Cities - Native support for Chinese city names / 原生支持中文城市名称
• Multiple Units - Celsius, Fahrenheit, Kelvin / 摄氏度、华氏度、开尔文

🇺🇸 US-Specific Features / 美国专用功能

• Weather Alerts - State-level weather alerts / 州级天气警报
• Coordinate Forecasts - Precise location-based forecasts / 基于坐标的精确预报

📦 Installation / 安装

npm install -g @chenxming/mcp-weather-server

Or use without installation:

npx @chenxming/mcp-weather-server

🚀 Quick Start / 快速开始

1. Get API Key / 获取API密钥

Get a free API key from OpenWeatherMap

在 OpenWeatherMap 注册获取免费API密钥

2. Configure MCP Client / 配置MCP客户端

Add to your MCP client configuration:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["@chenxming/mcp-weather-server"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

3. Alternative: Local Installation / 本地安装方式

{
  "mcpServers": {
    "weather": {
      "command": "mcp-weather",
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
}

🛠️ Available Tools / 可用工具

🌐 Global Weather Tools / 全球天气工具

get-current-weather

Get current weather for any city worldwide / 获取任意城市的当前天气

Parameters / 参数:

• city (required): City name in Chinese or English / 城市名称，支持中英文
• country (optional): Country code like CN, US / 国家代码
• units (optional): Temperature unit / 温度单位
  • metric (default): Celsius / 摄氏度
  • imperial: Fahrenheit / 华氏度
  • kelvin: Kelvin / 开尔文

Examples / 示例:

• Beijing: city: "北京" or city: "Beijing", country: "CN"
• New York: city: "New York", country: "US"

get-weather-forecast

Get 5-day weather forecast / 获取5天天气预报

Parameters / 参数:

• city (required): City name / 城市名称
• country (optional): Country code / 国家代码
• units (optional): Temperature unit / 温度单位

🇺🇸 US-Specific Tools / 美国专用工具

get-alerts

Get weather alerts for US states / 获取美国州级天气警报

Parameters / 参数:

• state (required): Two-letter state code / 两位字母州代码 (e.g., CA, NY)

get-forecast

Get coordinate-based forecast for US locations / 基于坐标的美国地区预报

Parameters / 参数:

• latitude (required): Latitude (-90 to 90) / 纬度
• longitude (required): Longitude (-180 to 180) / 经度

📝 Usage Examples / 使用示例

Query Chinese Cities / 查询中国城市

{
  "tool": "get-current-weather",
  "parameters": {
    "city": "上海",
    "units": "metric"
  }
}

Query Global Forecast / 查询全球预报

{
  "tool": "get-weather-forecast", 
  "parameters": {
    "city": "London",
    "country": "GB"
  }
}

US Weather Alerts / 美国天气警报

{
  "tool": "get-alerts",
  "parameters": {
    "state": "CA"
  }
}

🌏 Supported Cities / 支持的城市

• 🇨🇳 China: Beijing, Shanghai, Guangzhou, Shenzhen, Hangzhou, Chengdu...
• 🇺🇸 United States: New York, Los Angeles, Chicago, Houston...
• 🌍 Global: London, Tokyo, Paris, Sydney, Seoul, Mumbai...
• ✅ Chinese & English city names supported / 支持中英文城市名

🔧 Development / 开发

Local Setup / 本地设置

git clone https://github.com/chenxming/mcp-weather-server.git
cd mcp-weather-server
npm install
npm run build

Development Mode / 开发模式

npm run dev  # Watch mode

📊 API Data Sources / API数据源

• Global Weather: OpenWeatherMap API / 全球天气：OpenWeatherMap API
• US Weather: National Weather Service (NWS) API / 美国天气：国家气象服务API

⚡ Requirements / 系统要求

• Node.js >= 18.0.0
• OpenWeatherMap API key (free) / OpenWeatherMap API密钥（免费）

📄 License / 许可证

MIT License - see LICENSE file

🤝 Contributing / 贡献

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

🐛 Issues / 问题报告

Report issues at: https://github.com/chenxming/mcp-weather-server/issues

📞 Support / 支持

• GitHub Issues: Bug reports and feature requests
• Email: your.email@example.com