mcp-China-weather

This MCP server provides real-time and forecast weather information by leveraging the Amap (Gaode) weather APIs. It includes intelligent city-name recognition to convert standard Chinese city names into city codes and supports optional timezone handling. To use it, configure your environment with an Amap API key (AMAP_API_KEY) and start the server. The server exposes endpoints via the MCP protocol and accepts requests containing cityName, optional date, and forecast type to fetch either current conditions or future forecasts. Example requests show how to query a current weather for a city or retrieve a multi-day forecast for a given city and date. The build artifacts are produced from the TypeScript sources, and the runtime relies on Node.js 16+ with a valid API key.

Key capabilities:

• Real-time weather queries for Chinese cities
• Weather forecasts for upcoming days
• Smart city recognition to map city names to codes
• Timezone-aware formatting and output
• Clear error messages and handling for API or network issues

Prerequisites:

• Node.js 16.0 or higher
• npm (comes with Node.js)
• Amap (Gaode) API key for weather services

Installation steps:

1. Ensure you have Node.js installed. You can download it from https://nodejs.org/. Verify with: node -v

2. Clone or download this MCP server repository to your environment.

3. Install dependencies: npm install

4. Build the project (TypeScript to JavaScript): npm run build

5. Set up your environment variable for the Amap API key (example for Unix-like shells): export AMAP_API_KEY=your_gaode_api_key_here

6. Start the server (production): npm start

7. (Optional) Run in development mode while iterating: npm run dev

Notes:

• Ensure the AMAP_API_KEY is set in the environment before starting the server.
• The build/index.js path in the mcp_config should point to your actual built entry script after npm run build.

Tips and common considerations:

• API quota: The Gaode API has request limits depending on your account type; monitor usage accordingly.
• City name standardization: Use standard Chinese city names (e.g., 北京市, 上海市) for accurate city code mapping.
• Environment security: Keep your API key secure and avoid embedding it in public code.
• Network access: The server must have network access to Gaode API endpoints. Check firewall/proxy settings if requests fail.
• Error handling: If an error occurs (e.g., invalid city, invalid API key, network failure), the server should return clear error messages and status codes to help diagnose issues.