amap-weather

This MCP server provides access to real-time and forecast weather data for Chinese cities by leveraging the Amap (Gaode) Weather API. It exposes three main tools: get_current_weather, get_weather_forecast, and search_city. You can connect to the server using the MCP client and request weather information by city name (with proper administrative area identifiers like province/city/district). The server handles API calls to Gaode, parses responses, and returns human-readable weather strings or structured data, enabling easy integration into AI applications or chat clients.

To use the server, first ensure the environment variable AMAP_API_KEY is set with a valid Gaode API key. Start the server with uv run weather.py (or configure your MCP client to invoke the server as shown in the integration guide). Then, create a client connected to the server name amap-weather-mcp-server and call the available functions. For example, get_current_weather("北京市") retrieves the current conditions for Beijing, get_weather_forecast("上海市") fetches a forecast for Shanghai, and search_city("广州") returns city name matches for the keyword.

Prerequisites:

• A Gaode Map API key (AMAP_API_KEY) with permissions for weather data
• Python and the uv tool installed
• Git to clone the repository (optional)

Installation steps:

1. Clone or download the repository containing the MCP server.
2. Navigate into the project directory.
3. Create and activate a Python virtual environment (as shown by uv):

uv venv
source .venv/bin/activate

4. Install the necessary package for MCP CLI support:

uv add "mcp[cli]" httpx

5. Set your Gaode API key as an environment variable (preferred method):

export AMAP_API_KEY="YOUR_API_KEY_HERE"

6. Run the MCP server locally to test:

uv run weather.py

7. Optionally, configure you MCP client (e.g., Claude Desktop or Cherry Studio) to point to the server as described in the integration guide and ensure the AMAP_API_KEY environment variable is provided in the client configuration.

Tips and considerations:

• The service is limited to China mainland cities; ensure city names include provincial/municipal designators (e.g., 北京市, 上海市, 浙江省杭州市) for accurate results.
• The Gaode API may impose rate limits; plan for caching or throttling if integrating into high-traffic apps.
• When integrating into clients, you can pass city names to the three functions: get_current_weather, get_weather_forecast, and search_city. The forecast covers the next 3-4 days; current weather returns live conditions.
• If you encounter API failures, verify that AMAP_API_KEY is correctly loaded in the client environment and that the weather API endpoint is accessible from your network.
• The MCP server is designed to be easily embedded into AI workflows; consider exporting the formatted weather strings for display in chat interfaces or using the structured data for downstream processing.