weather-china-mcp

v1.0.4

Published

7 days ago

MCP server for China weather (weather.com.cn) — real-time weather, 5-day forecast, air quality. No API Key required. Works with Claude Desktop, Claude Code, Cursor, Cline, Windsurf, OpenCode.

中国天气网 MCP 服务

基于中国天气网（weather.com.cn）的 MCP 服务器，提供实时天气和 5 天预报查询。兼容 Claude Desktop、Claude Code、Cursor、Cline、Windsurf、OpenCode 等 AI 工具。

直接调用中国天气网官方接口，无需 API Key，免费使用。

快速安装（npm）

# 全局安装
npm install -g weather-china-mcp

然后在你的 MCP 客户端配置中添加：

{
  "mcpServers": {
    "weather-china": {
      "type": "stdio",
      "command": "weather-china-mcp",
      "args": []
    }
  }
}

或者直接用 npx（无需全局安装）：

{
  "mcpServers": {
    "weather-china": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "weather-china-mcp"]
    }
  }
}

配置

配置位置说明（项目级 vs 全局）

MCP 服务可以在两个位置配置，区别如下：

| 配置级别 | 配置文件位置 | 作用范围 | 适用客户端 | |----------|-------------|----------|-----------| | 项目级 | 项目根目录下的 .mcp.json / opencode.jsonc | 仅当前项目 | Claude Code、OpenCode | | 全局级 | 用户主目录下的配置文件 | 所有项目 | Claude Code、Claude Desktop、OpenCode、Cursor 等 |

方式一：项目级配置（仅当前项目生效）

适用场景：希望这个 MCP 服务只在某个特定项目中可用。

在项目根目录下创建 .mcp.json 文件：

<项目根目录>/
├── .mcp.json          ← 在这里创建
├── src/
├── package.json
└── ...

方式二：全局配置（推荐，所有项目生效）

适用场景：希望在任何项目、任何目录都能使用这个 MCP 服务。

2.1 Claude Code 全局配置

配置文件路径：

| 系统 | 完整路径 | |------|----------| | Windows | C:\Users\<你的用户名>\.claude.json | | macOS | /Users/<你的用户名>/.claude.json | | Linux | /home/<你的用户名>/.claude.json |

简写：~/.claude.json

在 ~/.claude.json 中添加 mcpServers 字段（详见下方安装方式）。

2.2 Claude Desktop 配置

| 系统 | 完整路径 | |------|----------| | Windows | %APPDATA%\Claude\claude_desktop_config.json | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |

2.3 OpenCode 全局配置

配置文件路径：

| 系统 | 完整路径 | |------|----------| | Windows | C:\Users\<你的用户名>\.config\opencode\opencode.jsonc | | macOS | ~/.config/opencode/opencode.jsonc | | Linux | ~/.config/opencode/opencode.jsonc |

简写：~/.config/opencode/opencode.jsonc

⚠️ 注意：OpenCode 的配置格式与 Claude Code 不同，详见下方 OpenCode 配置格式。

2.4 Cursor / Windsurf / Cline 等 IDE

| IDE | 配置方式 | |-----|----------| | Cursor | 设置面板 → MCP，或项目 .cursor/mcp.json | | Windsurf | 设置面板 → MCP | | Cline | 扩展设置 → MCP 配置 |

安装方式与配置内容

以下安装方式对应不同的 command + args，根据你的选择填入上述配置文件。

安装方式 A：GitHub 直装（npx，推荐）

无需克隆，直接通过 npx 从 GitHub 运行：

{
  "mcpServers": {
    "weather-china": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:zaixiamaomaoyu/weather-china-mcp"]
    }
  }
}

安装方式 B：本地克隆（Git Clone）

如果你是从 GitHub 克隆到本地运行的，需要先安装依赖，然后使用本地绝对路径：

git clone https://github.com/zaixiamaomaoyu/weather-china-mcp.git
cd weather-china-mcp
npm install

配置内容（将 <你的项目路径> 替换为实际路径）：

{
  "mcpServers": {
    "weather-china": {
      "type": "stdio",
      "command": "node",
      "args": ["<你的项目路径>/weather-china-mcp/src/index.js"]
    }
  }
}

示例：如果克隆到 D:\projects\weather-china-mcp，则路径为 D:/projects/weather-china-mcp/src/index.js

安装方式 C：npm 全局安装

npm install -g weather-china-mcp

配置内容：

{
  "mcpServers": {
    "weather-china": {
      "type": "stdio",
      "command": "weather-china-mcp",
      "args": []
    }
  }
}

安装方式 D：npm 包 + npx（不全局安装）

无需全局安装，直接用 npx 运行：

{
  "mcpServers": {
    "weather-china": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "weather-china-mcp"]
    }
  }
}

各安装方式对比

| 安装方式 | 是否需要克隆 | 是否需要全局安装 | 配置中的 command | 推荐度 | |----------|:---:|:---:|---|:---:| | A. GitHub 直装（npx） | ❌ | ❌ | npx -y github:... | ⭐⭐⭐ | | B. 本地克隆 | ✅ | ❌ | node <绝对路径> | ⭐⭐ | | C. npm 全局安装 | ❌ | ✅ | weather-china-mcp | ⭐⭐ | | D. npm + npx | ❌ | ❌ | npx -y weather-china-mcp | ⭐⭐⭐ |

OpenCode 配置格式

⚠️ OpenCode 的配置格式与 Claude Code 不同，主要差异如下：

| 差异项 | Claude Code | OpenCode | |--------|-------------|----------| | 顶层键 | mcpServers | mcp | | 类型关键字 | "stdio" | "local" | | 命令格式 | command: "npx" + args: ["-y", "..."] | command: ["npx", "-y", "..."]（合并为一个数组） | | 环境变量 | env: { "KEY": "val" } | environment: { "KEY": "val" } | | 支持注释 | ❌ | ✅（.jsonc 格式） |

OpenCode 配置示例

在 opencode.jsonc（项目级或全局）中添加：

// opencode.jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "weather-china": {
      "type": "local",
      "command": ["npx", "-y", "github:zaixiamaomaoyu/weather-china-mcp"],
      "enabled": true
    }
  }
}

OpenCode 各安装方式对应的 command

| 安装方式 | OpenCode 的 command 数组 | |----------|---------------------------| | A. GitHub 直装（推荐） | ["npx", "-y", "github:zaixiamaomaoyu/weather-china-mcp"] | | B. 本地克隆 | ["node", "<绝对路径>/weather-china-mcp/src/index.js"] | | C. npm 全局安装 | ["weather-china-mcp"] | | D. npm + npx | ["npx", "-y", "weather-china-mcp"] |

OpenCode MCP 管理命令

opencode mcp list          # 列出所有 MCP 服务器和认证状态
opencode mcp auth <name>   # 与需要 OAuth 的 MCP 服务器进行认证
opencode mcp debug <name>  # 调试连接/OAuth 问题
opencode mcp logout <name> # 移除已存储的凭证

配置验证

配置完成后，重启你的客户端，然后验证：

Claude Code：运行 /mcp，如果看到 weather-china 服务已连接并列出 weather_current、weather_forecast、weather_summary 三个工具，说明配置成功。

OpenCode：运行 opencode mcp list，如果看到 weather-china 状态为已连接，说明配置成功。

其他客户端：在对话中尝试调用天气查询，如"查询北京天气"。

可用工具

| 工具名称 | 描述 | 参数 | |---------|------|------| | weather_current | 实时天气（温度、湿度、PM2.5、空气质量、气压） | city（必填） | | weather_forecast | 5 天天气预报（含天气状况、高低温、风向风力） | city（必填） | | weather_summary | 天气摘要（实时 + 今天 + 明天） | city（必填） |

支持的城市

支持任意中文城市名查询，查找逻辑如下：

本地映射表（city-codes-complete.json，含 2732 个城市/区县）
- 精确匹配（如 广州）
- 自动去后缀（如 广州市 → 广州）
- 模糊匹配（如输入部分城市名）
在线搜索 fallback（中国天气网内部搜索接口）
- 本地表找不到时，自动按城市名在线搜索代码
- 搜索到后自动缓存到本地，下次无需再请求网络
- 支持镇级地名（自动映射到上级市级数据）

数据源

| 项目 | 说明 | |------|------| | 数据来源 | 中国天气网 weather.com.cn | | 天气接口 | http://d1.weather.com.cn/weather_index/{城市代码}.html | | 搜索接口 | http://toy1.weather.com.cn/search?cityname=城市名 | | 认证方式 | 无需 API Key |

注意事项

预报天数：weather_forecast 返回 5 天预报，这是中国天气网官方接口 fc 数组能提供的最大天数，无法获取 7 天或 15 天数据。

返回数据示例

weather_current

{
  "city": "广州",
  "temperature_c": "28.8",
  "weather": "多云",
  "wind": "西南风 1级",
  "humidity_pct": "84%",
  "pressure_hpa": "998",
  "aqi": "36",
  "pm25": "36",
  "updateTime": "18:30",
  "notice": "多云转晴，南风转微风 3-4级转<3级"
}

weather_forecast

{
  "city": "广州",
  "updateTime": "18:30",
  "days": 5,
  "forecast": [
    {
      "date": "7/22",
      "week": "今天",
      "weather_day": "多云",
      "weather_night": "晴",
      "temp_high": "33℃",
      "temp_low": "25℃",
      "wind_day": "南风 3-4级",
      "wind_night": "无持续风向 <3级"
    }
  ]
}

weather_summary

{
  "city": "广州",
  "updateTime": "18:30",
  "current": {
    "temperature_c": "28.8",
    "humidity_pct": "84%",
    "weather": "多云",
    "wind": "西南风 1级",
    "aqi": "36",
    "pm25": "36"
  },
  "today": {
    "date": "7/22",
    "week": "今天",
    "weather_day": "多云",
    "weather_night": "晴",
    "temp_high": "33℃",
    "temp_low": "25℃",
    "wind": "南风 3-4级"
  },
  "tomorrow": {
    "date": "7/23",
    "week": "星期四",
    "weather_day": "晴",
    "weather_night": "晴",
    "temp_high": "34℃",
    "temp_low": "26℃",
    "wind": "无持续风向 <3级"
  }
}

依赖

@modelcontextprotocol/sdk — MCP 协议 SDK

许可证

MIT