China Weather MCP Service

[smithery badge](https://smithery.ai/server/@jikime/py-mcp-cn-weather) Version License

This MCP (Multi-Platform Communication Protocol) service provides access to the China Meteorological Administration API, allowing AI agents to obtain weather forecast information for regions in China.

Overview

• Obtain precise grid coordinates (province, city, district) for Chinese administrative divisions
• Provide detailed short-term weather forecasts
• Support all administrative divisions in China (provinces, cities, districts)
• Structured text responses, optimized for large language model processing
• Includes complete weather data: temperature, precipitation, sky conditions, humidity, wind direction, and wind speed

Table of Contents

• Prerequisites for Installation
• Installation Steps
• Configuring MCP Settings
• API Reference
• Acknowledgments
• License

Installation Instructions

Prerequisites for Installation

• Python 3.12+
• China Meteorological Administration API credentials
• Register and apply for API access from the China Meteorological Data Network

Installation Steps

1. Clone the repository:
   bash
   git clone https://github.com/jikime/py-mcp-cn-weather.git
   cd py-mcp-cn-weather

2. Install uv
   bash
   curl -LsSf https://astral.sh/uv/install.sh | sh

3. Create a virtual environment and install dependencies:
   bash
   uv venv -p 3.12
   source .venv/bin/activate
   uv pip install -r requirements.txt

4. Create a .env file and fill in your China Meteorological Administration API credentials:
   bash
   cp env.example .env
   vi .env

CN_WEATHER_API_KEY=your_api_key_here

1. Migrate the grid coordinate data from Excel to an SQLite database:
   bash
   uv run src/migrate.py

Docker Installation

1. Build the image:
   bash
   docker build -t py-mcp-cn-weather .

2. Run the container:
   bash
   docker run py-mcp-cn-weather

Running Locally

1. Start the server:
   bash
   mcp run src/server.py

2. Run MCP Inspector
   bash
   mcp dev server.py

Configuring MCP Settings

Add the following server configuration to your MCP settings file:

Claude Desktop Application

1. Automatic installation via Smithery:

bash
npx -y @smithery/cli install @jikime/py-mcp-cn-weather --client claude

1. Manual Installation
   Open ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following content to the mcpServers object:
json
{
"mcpServers": {
"China Weather Toolbox": {
"command": "/path/to/bin/uv",
"args": [
"--directory",
"/path/to/py-mcp-cn-weather",
"run",
"src/server.py"
]
}
}
}

Cursor IDE

Open ~/.cursor/mcp.json

Add the following content to the mcpServers object:
json
{
"mcpServers": {
"China Weather Toolbox": {
"command": "/path/to/bin/uv",
"args": [
"--directory",
"/path/to/py-mcp-cn-weather",
"run",
"src/server.py"
]
}
}
}

For Docker Users

json
{
"mcpServers": {
"China Weather Toolbox": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"py-mcp-cn-weather"
]
}
}
}

Using in Claude

After configuration, you can ask Claude questions like:

• "What's the weather like in Chaoyang District, Beijing?"
• "Please tell me the weather forecast for Pudong New Area, Shanghai."
• "What is the current temperature in Tianhe District, Guangzhou, Guangdong Province?"

API Reference

Tools

Get Grid Location

get_grid_location(province: str, city: str, district: str) -> dict

Obtain the corresponding grid coordinates (grid_x, grid_y) for the specified area, used for calling the China Meteorological Administration API.
This tool queries the exact coordinates based on the province, city, and district information in the database.

Get Weather Forecast

get_forecast(province: str, city: str, district: str, grid_x: int, grid_y: int) -> strCalling the China Meteorological Administration's short-term weather forecast API provides weather information for specific regions.
It returns comprehensive weather data including temperature, precipitation, sky conditions, humidity, wind direction, and wind speed.

Resources

Weather Instructions Document

GET weather://instructions

Provides detailed documentation on how to use the China Weather MCP service, including workflow of tools and response format explanations.

Prompt Words

Weather Query

The server includes a structured weather query prompt template that guides the conversation flow, ensuring efficient information gathering and clear presentation of forecast results.

Response Format

The weather forecast response adopts a structured text format, optimizing processing efficiency for large language models:

Weather forecast for Chaoyang District, Beijing (coordinates: grid_x=61, grid_y=125)
Date: 2025-05-01
Time: 15:00

Current Conditions:
Temperature: 22.3°C
Sky Condition: Clear
Precipitation: None
Probability of Precipitation: 0%
Humidity: 45%
Wind Direction: Northwest
Wind Speed: 2.3 m/s

Hourly Forecast:
16:00 - Temperature: 21.8°C, Sky: Clear, Precipitation: None
17:00 - Temperature: 20.5°C, Sky: Clear, Precipitation: None
18:00 - Temperature: 19.2°C, Sky: Clear, Precipitation: None
...

Acknowledgments

• China Meteorological Administration
• China Meteorological Data Network
• MCP Protocol

License

This project is licensed under the MIT License - see the LICENSE file for details.