@mariox/weather-mcp-server/README.md

MCP server for querying weather by current IP location using Open-Meteo free API

# Weather MCP Server

一个基于 Model Context Protocol (MCP) 的智能天气查询服务器，支持自动识别当前位置或查询指定地点的天气信息。使用免费的 Open-Meteo API 和 OpenStreetMap 地理编码服务，无需注册或 API 密钥。

## 功能特性

- 🌍 **智能位置识别**：不指定地点时自动查询当前IP位置天气
- 🗺️ **地点名称查询**：支持中英文地点名称，如"北京"、"上海"、"Tokyo"、"New York"
- 🌤️ **实时天气查询**：获取任意地点的实时天气信息
- 📅 **天气预报**：支持未来7天天气预报，可指定地点或使用当前位置
- 📍 **精确坐标查询**：支持经纬度精确查询（高级用法）
- 🆓 **完全免费**：使用免费API服务，无需注册或API密钥
- 🚀 **即装即用**：一行命令安装，无需额外配置
- 🌐 **地理编码**：自动将地点名称转换为精确坐标

## 可用工具

1. **get_weather** - 智能天气查询，不指定地点时查询当前位置，指定地点时查询该地点天气
2. **get_weather_forecast** - 智能天气预报，支持指定地点或当前位置的未来7天预报
3. **get_current_ip_info** - 获取当前IP地址的详细位置信息
4. **get_weather_by_coordinates** - 根据精确坐标获取天气信息（高级用法）

## 快速开始

### 方法一：通过 npm 安装（推荐）

```bash
# 全局安装
npm install -g @mariox/weather-mcp-server

# 或者使用 npx（无需全局安装）
npx @mariox/weather-mcp-server
```

### 方法二：本地开发

```bash
# 克隆仓库
git clone https://github.com/mariox/weather-mcp-server.git
cd weather-mcp-server

# 安装依赖
npm install

# 启动服务器
npm start
```

## MCP 客户端配置

### Claude Desktop 配置

在 Claude Desktop 的配置文件中添加以下内容：

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["@mariox/weather-mcp-server"]
    }
  }
}
```

### Cursor 配置

在 Cursor 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@mariox/weather-mcp-server"]
    }
  }
}
```

### 其他 MCP 客户端配置

对于支持 MCP 的其他客户端，使用以下通用配置：

```json
{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["@mariox/weather-mcp-server"],
      "env": {}
    }
  }
}
```

### 本地开发配置

如果您是从源码本地运行，请使用：

```json
{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/your/weather-mcp-server/index.js"],
      "cwd": "/path/to/your/weather-mcp-server"
    }
  }
}
```

## 配置验证

配置完成后，重启您的 MCP 客户端，您应该能看到以下工具可用：

- ✅ `get_weather` - 智能天气查询，不指定地点时查询当前位置，指定地点时查询该地点天气
- ✅ `get_weather_forecast` - 智能天气预报，支持指定地点或当前位置的未来7天预报
- ✅ `get_current_ip_info` - 获取当前IP地址的详细位置信息
- ✅ `get_weather_by_coordinates` - 根据精确坐标获取天气信息（高级用法）

## 测试安装

您可以通过以下命令快速测试包是否正常工作：

```bash
# 测试版本信息
npx @mariox/weather-mcp-server --version

# 查看帮助信息
npx @mariox/weather-mcp-server --help

# 测试MCP服务器（会启动服务器，按Ctrl+C退出）
npx @mariox/weather-mcp-server
```

如果看到类似以下输出，说明安装成功：
```
Weather MCP Server 已启动
```

## 使用示例

### 智能天气查询

#### 查询当前位置天气（自动识别IP位置）
```
今天天气怎么样？
查询当前位置的天气
现在的天气情况
```

#### 查询指定地点天气
```
北京的天气怎么样？
查询上海的天气
Tokyo weather
New York的天气情况
```

### 智能天气预报

#### 当前位置天气预报
```
未来三天的天气预报
获取本周天气预报
明天天气怎么样？
```

#### 指定地点天气预报
```
北京未来5天的天气预报
查询东京下周的天气
Paris 7天天气预报
```

### 高级用法

#### 精确坐标查询
```
查询坐标 39.9042, 116.4074 的天气（北京）
获取纬度 35.6762 经度 139.6503 的天气（东京）
```

#### IP位置信息查询
```
显示我当前的IP地址和位置信息
获取当前IP的详细信息
```

### 支持的地点格式

- **中文城市名**：北京、上海、广州、深圳、成都、杭州等
- **英文城市名**：Tokyo, New York, London, Paris, Sydney等
- **国家名**：China, Japan, USA, UK, France等
- **详细地址**：天安门广场、Times Square、Eiffel Tower等
- **拼音**：Beijing, Shanghai, Guangzhou等

## 故障排除

### 1. 工具无法识别

如果客户端显示 "No tools available"：

1. 确认已正确配置 `claude_desktop_config.json` 文件
2. 重启 Claude Desktop 或相关客户端
3. 检查 npm 包是否正确安装：`npm list -g @mariox/weather-mcp-server`

### 2. 网络连接问题

确保您的网络可以访问以下服务：
- `ip-api.com` (IP地理位置服务)
- `api.open-meteo.com` (天气数据服务)
- `nominatim.openstreetmap.org` (地理编码服务)

如果地理编码服务响应较慢，可以：
1. 使用精确的坐标查询代替地点名称
2. 检查网络连接稳定性
3. 尝试使用更具体的地点名称

### 3. Node.js 版本要求

确保 Node.js 版本 >= 18.0.0：
```bash
node --version
```

## 技术栈

- **运行环境**: Node.js 18+
- **MCP 协议**: @modelcontextprotocol/sdk ^0.5.0
- **HTTP 客户端**: axios ^1.6.0
- **天气数据**: Open-Meteo API（免费服务）
- **地理编码**: OpenStreetMap Nominatim（免费服务）
- **IP位置**: ip-api.com（免费服务）

## API 数据源

- **IP 地理位置信息**：[ip-api.com](https://ip-api.com/)（免费服务，无需API密钥）
- **天气数据**：[Open-Meteo API](https://open-meteo.com/)（完全免费，无需注册）
- **地理编码服务**：[OpenStreetMap Nominatim](https://nominatim.openstreetmap.org/)（免费地理编码服务）

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 贡献

欢迎提交 Issues 和 Pull Requests！

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/new-feature`
3. 提交更改：`git commit -am 'Add new feature'`
4. 推送分支：`git push origin feature/new-feature`
5. 提交 Pull Request

## 更新日志

### v1.1.0 (2024-12-19)
- 🎉 **重大功能更新**：智能地点查询系统
- ✨ 新增智能天气查询工具 `get_weather`
- ✨ 新增智能天气预报工具 `get_weather_forecast`
- 🌐 集成OpenStreetMap地理编码服务
- 🗺️ 支持中英文地点名称查询（北京、Tokyo、New York等）
- 🤖 智能识别：不指定地点时自动查询当前IP位置
- 📝 更新了工具描述和使用文档
- 🔧 优化了工具组织结构，保留高级坐标查询功能

### v1.0.3 (2024-12-19)
- 🐛 修复了npm包bin路径问题
- ✨ 添加了命令行参数支持（--version, --help）
- 📝 完善了配置文档和故障排除指南

### v1.0.2 (2024-12-19)
- ✨ 添加了命令行参数支持

### v1.0.1 (2024-12-19)
- 📝 更新了文档和配置说明

### v1.0.0 (2024-12-19)
- 🎉 初始版本发布
- ✨ 支持当前 IP 天气查询
- ✨ 支持经纬度天气查询
- ✨ 支持 IP 信息查询
- ✨ 支持天气预报功能
- 📦 发布到 npm: `@mariox/weather-mcp-server`

## 联系方式

- GitHub: [@mariox](https://github.com/mariox)
- NPM: [@mariox/weather-mcp-server](https://www.npmjs.com/package/@mariox/weather-mcp-server)