Skip to main content
Glama
killerfirst

weather-china-mcp

by killerfirst
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

🌤 Weather China MCP Server

A Model Context Protocol (MCP) server that provides real-time weather and 3-day forecast for Chinese cities, powered by QWeather (和风天气) API.

Inspiration: This project is a learning exercise by the author, inspired by the MCP server weather tutorial on modelcontextprotocol.io — which demonstrated building a US weather MCP server. This is the Chinese weather counterpart, adapted for the QWeather API.

✨ Features

  • Real-time weather — temperature, feels-like, humidity, wind, visibility, and more

  • 3-day forecast — daily high/low, day/night weather, humidity, wind

  • MCP-native — works with any MCP-compatible client (Claude Code, Codex, OpenClaw, etc.)

  • Secure — API credentials stored in .env, never committed to Git

Related MCP server: AMap Weather MCP

📋 Prerequisites

Requirement

Description

Python

≥ 3.11

uv

Python package manager (install)

QWeather Account

Free tier: 1,000 calls/day. Register at console.qweather.com

After registering on QWeather Console:

  1. Create a project → get your API Key

  2. Go to Settings → copy your dedicated API Host (format: xxx.xxx.qweatherapi.com)

🚀 Quick Start

# 1. Clone the repo
git clone <your-repo-url>
cd weather-china

# 2. Set up environment variables
cp .env.example .env
# Edit .env and fill in your QWeather API Key & API Host

# 3. Install dependencies
uv sync

# 4. Run the server (for testing)
uv run weather.py

🔧 MCP Client Configuration

Claude Code

Add to .mcp.json in your project root (or ~/.claude/mcp.json for global):

{
  "mcpServers": {
    "weather-china": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-china",
        "run",
        "weather.py"
      ]
    }
  }
}

Restart Claude Code or run /mcp reload to pick up the change.

Codex (OpenAI)

In Codex, open Settings → MCP Servers → Add:

{
  "mcpServers": {
    "weather-china": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-china",
        "run",
        "weather.py"
      ]
    }
  }
}

OpenClaw

Add to your OpenClaw MCP configuration file:

mcp_servers:
  weather-china:
    command: uv
    args:
      - --directory
      - /path/to/weather-china
      - run
      - weather.py

Other MCP Clients (Generic stdio)

Any MCP client that supports stdio transport:

{
  "mcpServers": {
    "weather-china": {
      "command": "uv",
      "args": ["--directory", "/path/to/weather-china", "run", "weather.py"],
      "env": {
        "QWEATHER_API_KEY": "<your-api-key>",
        "QWEATHER_API_HOST": "<your-api-host>"
      }
    }
  }
}

Note: If your client doesn't inherit shell environment variables, pass QWEATHER_API_KEY and QWEATHER_API_HOST via the env field as shown above. When using .env file, the server loads them automatically.

🛠 Available Tools

get_weather

Get real-time weather for a Chinese city.

Parameters:
  city: string — City name (e.g., "北京", "上海", "广州")

get_forecast

Get 3-day weather forecast for a Chinese city.

Parameters:
  city: string — City name (e.g., "北京", "上海", "广州")

📁 Project Structure

weather-china/
├── weather.py          # MCP server — main entry point
├── main.py             # Placeholder entry
├── .env.example        # Environment variable template
├── .env                # Your credentials (gitignored)
├── .gitignore
├── .mcp.json           # Claude Code MCP config (example)
├── pyproject.toml      # Python project metadata & dependencies
├── uv.lock             # Dependency lock file
├── README.md           # English readme
└── README.zh.md        # Chinese readme

🔒 Security

  • .env is listed in .gitignore — never commit your API credentials

  • .env.example provides a template for others to set up their own credentials

  • Both QWEATHER_API_KEY and QWEATHER_API_HOST are read from environment variables, not hardcoded

📄 License

MIT

Available Tools

2 tools
get_forecastA

获取中国城市未来3天的天气预报

Args:
    city: 城市名称，例如"北京"、"上海"、"广州"
ParametersJSON Schema
NameRequiredDescriptionDefault
cityYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior3/5

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

No annotations are provided, so the description must convey behavioral context. It discloses the forecast's timeframe (3 days) and geographic scope (Chinese cities), which is helpful. It does not mention output format, units, or failure behavior, but the presence of an output schema covers some of that information externally.

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 and front-loaded: one purpose sentence and one parameter line with examples. Every element adds value, and there is no filler or redundancy.

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?

For a simple one-parameter tool with an output schema, the description is almost complete. The main gap is the absence of differentiation from the sibling get_weather, which could cause incorrect tool selection despite the clear purpose and parameter guidance.

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?

The input schema offers no description for the city parameter (0% coverage). The description compensates by explaining that city is a Chinese city name and gives concrete examples (北京, 上海, 广州), making the expected input clear and actionable.

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 the tool's function: retrieving a 3-day weather forecast for Chinese cities. It includes a specific verb (获取), resource, scope, and time window. However, it does not explicitly differentiate itself from the sibling get_weather, so an agent may not know which tool to choose for a given request.

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 when to use this tool—when a Chinese city's 3-day forecast is needed—but provides no explicit guidance on alternatives or conditions. It does not mention get_weather or explain cases where one tool should be preferred over the other.

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

get_weatherA

获取中国城市的实时天气 Get weather for chinese city

Args:
city:城市名称,例如"北京","上海","广州"
ParametersJSON Schema
NameRequiredDescriptionDefault
cityYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations provided, the description carries the behavioral disclosure burden. It does convey that the tool returns real-time weather and is scoped to Chinese cities. However, it does not mention units, response behavior for invalid cities, data source, or refresh characteristics. This is adequate for a simple read-only tool but not particularly rich.

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 compact and front-loaded with the core purpose, followed immediately by the parameter explanation. The bilingual repetition adds slight redundancy but is not bloated. The structure is appropriate for a single-parameter tool.

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?

Because an output schema exists, return-value details are not required in the description. The geographic scope and real-time nature are covered, and the single parameter is well explained. However, the lack of guidance about the sibling get_forecast leaves a noticeable contextual gap for correct tool selection.

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%, so the description must compensate. It does: 'city:城市名称' explains the semantic meaning of the parameter and provides concrete examples like '北京', '上海', '广州'. This gives an agent enough information to construct a valid call despite the empty schema.

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 the tool's function in both Chinese and English: getting real-time weather for a Chinese city. The verb-resource-scope combination is specific and unambiguous. However, it does not distinguish itself from the sibling tool get_forecast, keeping it from a 5.

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 word '实时' (real-time) implies this is for current conditions rather than forecasts, which offers some usage context. But there is no explicit guidance on when to choose get_weather versus get_forecast, nor any exclusionary conditions. Usage intent must be inferred rather than stated.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_forecast
    • First observedget_weather
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are clearly distinct: one provides real-time current weather, the other provides a 3-day forecast. There is no overlap or ambiguity in their purposes.

Naming Consistency5/5

Both tools follow the exact same verb_noun pattern (get_weather, get_forecast), using consistent snake_case and a clear 'get_' prefix.

Tool Count3/5

With only 2 tools, the server feels thin for a weather service, but it is functional for basic real-time and forecast queries. This falls on the borderline low end.

Completeness3/5

The core weather operations (current conditions and forecast) are covered, but gaps exist for additional useful features like air quality, historical data, or location suggestions, which agents might expect from a comprehensive weather server.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • AMap Weather MCP

    KaguyaRing
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides real-time weather information, 4-day forecasts, and city search functionality for Chinese cities via the AMap API. It enables users to query weather data using city names or administrative codes through natural language interactions.
    1
    MIT

  • Weather MCP Server

    smallwhitelz
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server integrated with the QWeather API that provides real-time weather forecasts and meteorological warnings for AI assistants. It enables users to query current conditions and disaster alerts for specific cities or coordinates.
    15 npm
    -