Skip to main content
Glama
DongDong1997

Weather MCP Server

by DongDong1997
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Weather MCP Server

基于 和风天气 API 的 Model Context Protocol (MCP) 服务器，让 Claude / Cursor / Cline 等 MCP 客户端能够查询中国城市的实时天气、预报和预警。

✨ 功能特性

工具

功能

输入

get_current_weather

查询实时天气

城市名 / 经纬度 / Location ID

get_forecast

查询未来 3/7/10/15/30 天天气预报

城市名 + 天数

get_warnings

查询当前生效中的气象灾害预警

城市名 / 经纬度 / Location ID

  • 🔒 API Key 不入源码——通过环境变量或 .mcp.json 注入

  • 🌍 GeoAPI 自动解析——支持「北京」「上海」等中文城市名，也支持 116.41,39.92 经纬度

  • 📐 公制 / 英制可切换——get_current_weather 支持 unit=m/i 参数

  • 🌐 多语言——支持 lang=zh/en/...

Related MCP server: HeFeng Weather MCP Server

🚀 快速开始

1. 获取和风天气 API Key

前往 和风天气控制台 → 注册 → 创建项目 → 拿到 API Key（推荐重置一次以确保 Key 安全）。

2. 准备环境

需要 uv（推荐）或 Python 3.10+。

# 克隆 / 进入项目目录
cd F:\code\weather

# 同步依赖
uv sync

3. 配置环境变量

将 Key 写入 .mcp.json（推荐，详见下方 MCP 客户端配置）或系统环境变量：

# PowerShell
$env:WEATHER_API_KEY = "你的key"

# Bash
export WEATHER_API_KEY="你的key"

4. 测试连通性

uv run weather.py

服务器启动后会在 stdio 上等待 MCP 客户端连接，不会自己产生输出——这是正常行为。

⚙️ 配置

API Host

weather.py:7 中配置的是专属子域名，使用 X-QW-Api-Key 请求头鉴权：

QWEATHER_HOST = "https://<your-sub>.re.qweatherapi.com"

如需改回公共域名（devapi.qweather.com / geoapi.qweather.com），将 host 替换即可，鉴权方式相应改为 URL ?key= 参数。

环境变量

变量名

必填

说明

WEATHER_API_KEY

✅

和风天气 API Key

🔌 MCP 客户端配置

Claude Code（项目级，推荐）

新建 .mcp.json：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["run", "weather.py"],
      "env": {
        "WEATHER_API_KEY": "你的key"
      }
    }
  }
}

重启 Claude Code 后，在对话中输入 /mcp 应能看到 weather: connected · 3 tools。

Claude Desktop

编辑 %APPDATA%\Claude\claude_desktop_config.json：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": ["--directory", "F:\\code\\weather", "run", "weather.py"],
      "env": { "WEATHER_API_KEY": "你的key" }
    }
  }
}

MCP Inspector（调试用）

uv run --with "mcp[cli]" mcp dev weather.py

会自动打开浏览器调试控制台。

💬 使用示例

在配置好 MCP 的客户端中直接用自然语言提问：

杭州今天天气怎么样？
上海未来 7 天天气预报
北京有没有台风预警？
116.41, 39.92 这个坐标的天气
用英制单位查东京当前天气

LLM 会自动选择并调用合适的工具。

📁 项目结构

weather/
├── .mcp.json            # Claude Code MCP 配置
├── .python-version      # Python 版本声明（3.10）
├── .venv/               # 虚拟环境（uv 管理）
├── .gitignore
├── pyproject.toml       # 项目元数据 + 依赖
├── uv.lock              # 锁定依赖版本
├── main.py              # 入口占位（未使用）
├── weather.py           # ⭐ MCP 服务器主程序
└── README.md            # 本文件

🛠️ 开发

依赖

包

版本

用途

httpx

≥ 0.28.1

异步 HTTP 客户端

mcp[cli]

≥ 1.28.1

MCP 协议 SDK

添加工具

在 weather.py 中用 @mcp.tool() 装饰器注册新函数：

@mcp.tool()
async def my_new_tool(arg: str) -> str:
    """工具描述（LLM 据此决定何时调用）。"""
    ...

接口规范适配进度

接口

状态

/v7/weather/now 实时天气

✅ 按规范展开全字段

/v7/weather/{3,7,10,15,30}d 天气预报

🟡 基本功能，待按规范补字段

/v7/warning/now 天气预警

🟡 基本功能，待按规范补字段

/geo/v2/city/lookup 城市解析

🟡 仅返回 Location ID，未暴露其他字段

⚠️ 安全提示

  • 永远不要把 API Key 硬编码进源码——使用环境变量或 .mcp.json 的 env 字段

  • 不要把 .mcp.json 提交到公开仓库——如果必须提交，把 Key 改成环境变量占位符

  • 泄露的 Key 应立即去和风天气控制台重置

📝 License

MIT

Available Tools

3 tools
get_current_weatherA

获取指定城市的实时天气。

Args:
    location: 城市名称（如"北京"）、经纬度（格式"lng,lat"如"116.41,39.92"）或 Location ID。
    lang: 可选，多语言设置（如 "zh"、"en"），不传则用服务端默认。
    unit: 可选，数据单位，"m" 公制（默认）/"i" 英制。
ParametersJSON Schema
NameRequiredDescriptionDefault
langNo
unitNo
locationYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose any behavioral traits such as data freshness, accuracy, rate limits, or side effects. It only covers parameter formats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the main purpose. The parameter documentation is structured clearly, though it follows a standard docstring format.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema but the description does not explain return values or behavior. Given the complexity and lack of annotations, more context on behavior would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds significant value by detailing the three formats for location, multi-language options for lang, and metric/imperial units for unit, beyond the basic type definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it gets real-time weather for a specified city, using a specific verb and resource. It distinguishes from siblings like get_forecast and get_warnings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for current weather but does not explicitly state when to use this tool versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_forecastB

获取指定城市的天气预报。

Args:
    location: 城市名称、经纬度（"lng,lat"）或 Location ID。
    days: 预报天数，支持 3 / 7 / 10 / 15 / 30 天，默认 7 天。
ParametersJSON Schema
NameRequiredDescriptionDefault
daysNo
locationYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description omits behavioral details such as rate limits, data freshness, or error handling. With no annotations, the agent is left unaware of potential side effects or restrictions beyond the basic input-output expectation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, using two sentences to cover both the purpose and parameter semantics. It is efficiently front-loaded, with every word adding value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description adequately explains the input parameters and an output schema exists, it lacks context about the forecast's temporal coverage (e.g., daily breakdown) and does not highlight differences from sibling tools. It meets minimum viability but leaves gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description compensates well by explaining that location accepts city names, coordinates, or IDs, and that days must be one of 3/7/10/15/30. This adds essential meaning beyond the bare type definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves a weather forecast for a specified city, effectively communicating the core function. However, it does not explicitly distinguish this tool from siblings like get_current_weather or get_warnings, relying on the tool name and implicit context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus its siblings (e.g., for short-term conditions vs. warnings). The description only lists parameters without suggesting appropriate contexts or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_warningsA

获取指定城市当前生效中的天气预警。

Args:
    location: 城市名称、经纬度（"lng,lat"）或 Location ID。
ParametersJSON Schema
NameRequiredDescriptionDefault
locationYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries full burden. It only states it gets current warnings, with no disclosure of data freshness, rate limits, or scope of warnings (e.g., types). Minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise with two sentences. The first sentence immediately states the purpose. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, return values are covered. However, for a simple tool, more context about data source, update frequency, or selection criteria versus sibling tools would improve completeness. Currently adequate but minimal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds meaning by explaining that 'location' can be a city name, lat/lng, or Location ID. However, it does not provide examples or clarify what a Location ID is, so it only partially compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (获取/get) and resource (天气预警/weather warnings) with specificity ('当前生效中' meaning currently active). It distinguishes from sibling tools (get_current_weather, get_forecast) by focusing on warnings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied (when you need weather warnings) but no explicit when-to-use or when-not-to-use guidance is provided. No alternatives are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool addresses a distinct weather information need: current conditions, forecast, and warnings. There is no functional overlap.

Naming Consistency5/5

All tool names follow the 'get_<resource>' pattern (get_current_weather, get_forecast, get_warnings), ensuring predictability.

Tool Count5/5

Three tools cover the essential weather functions (current, forecast, warnings) without being too few or excessive.

Completeness4/5

Core weather data needs are met, but optional features like historical data or air quality are absent. Minor gap, but acceptable for a focused weather server.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Weather API MCP Server

    yoyooyooo
    A
    license
    B
    quality
    D
    maintenance
    Provides current weather data, multi-day forecasts, hourly forecasts, and city lookup functionality using the QWeather API. Supports customizable units, languages, and multiple location formats including coordinates and city IDs.
    4
    22
    1
    MIT

  • China Weather MCP Server

    nanchengjiumeng
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables querying weather forecasts (1-7 days) and meteorological warnings for Chinese cities using the QWeather API. Supports detailed weather data including temperature, humidity, wind, precipitation, UV index, and real-time weather alerts.
    1

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/DongDong1997/weather'

If you have feedback or need assistance with the MCP directory API, please join our Discord server