# 🌤️ MCP Weather Server / 全球天气MCP服务器
[](https://badge.fury.io/js/%40chenxming%2Fmcp-weather-server)
[](https://opensource.org/licenses/MIT)
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 / 安装
```bash
npm install -g @chenxming/mcp-weather-server
```
Or use without installation:
```bash
npx @chenxming/mcp-weather-server
```
## 🚀 Quick Start / 快速开始
### 1. Get API Key / 获取API密钥
Get a free API key from [OpenWeatherMap](https://openweathermap.org/api)
在 [OpenWeatherMap](https://openweathermap.org/api) 注册获取免费API密钥
### 2. Configure MCP Client / 配置MCP客户端
Add to your MCP client configuration:
```json
{
"mcpServers": {
"weather": {
"command": "npx",
"args": ["@chenxming/mcp-weather-server"],
"env": {
"OPENWEATHER_API_KEY": "your_api_key_here"
}
}
}
}
```
### 3. Alternative: Local Installation / 本地安装方式
```json
{
"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 / 查询中国城市
```json
{
"tool": "get-current-weather",
"parameters": {
"city": "上海",
"units": "metric"
}
}
```
### Query Global Forecast / 查询全球预报
```json
{
"tool": "get-weather-forecast",
"parameters": {
"city": "London",
"country": "GB"
}
}
```
### US Weather Alerts / 美国天气警报
```json
{
"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 / 本地设置
```bash
git clone https://github.com/chenxming/mcp-weather-server.git
cd mcp-weather-server
npm install
npm run build
```
### Development Mode / 开发模式
```bash
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](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
