AMAP Weather

Provides real-time weather and city search data via MCP using the AMap API.

python

1

GitHub Stars

python

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "churanneko-amap-weather-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/amap-weather-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "AMAP_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

This MCP server provides real-time weather data and city code search by leveraging the AMap API. It enables you to query weather by city name or adcode, search Chinese cities, fetch a 4-day forecast, and list all available cities. It is designed to integrate with MCP clients to deliver weather information in a structured, context-aware way.

How to use

You interact with the amap_weather_mcp through an MCP-enabled client. Use the following capabilities to retrieve weather data and city information without writing custom API calls.

How to install

Prerequisites: ensure you have Python 3.8+ installed on your system.

Clone the project repository and navigate into it.
Install dependencies using the recommended package manager.
Set up your environment variable AMAP_API_KEY with your High DeMap API key.
Start the MCP server using the provided runtime command.

Configuration and runtime

{
  "mcpServers": {
    "amap_weather_mcp": {
      "name": "amap_weather_mcp",
      "type": "stdio",
      "isActive": true,
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/amap-weather-mcp",
        "run",
        "main.py"
      ],
      "env": {
        "AMAP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment and runtime details

Environment variables you need to configure:

AMAP_API_KEY: High-definition map API key required to query weather data.

Notes on running: the server runs as a stdio MCP server using the uv runtime. The command and arguments must be provided exactly as shown in the runtime snippet above.

Usage endpoints and tools

This server exposes a set of MCP tools to fetch weather data and city information. Each tool takes specific parameters and returns structured results that include real-time weather data and a 4-day forecast.

Available tools include the following functions:

get_weather_by_city_name: Retrieve weather by city name (e.g., 杭州市, 北京市). Returns real-time weather and a 4-day forecast.
get_weather_by_city_code: Retrieve weather by city administrative code (e.g., 110100). Returns real-time weather and a 4-day forecast.
search_city: Search for cities by name with exact or fuzzy matching. Returns a list of matching cities and their codes.
get_city_by_adcode: Retrieve city information by adcode (e.g., 110000 for Beijing). Returns the city information object.
list_all_cities: List all available cities with an optional limit (default 50, max 200). Returns the total count and a city list.

Project structure and dependencies

The project includes a main program file, a city code database, and dependencies that enable asynchronous HTTP calls and MCP support.

Available tools

get_weather_by_city_name

Query real-time weather and 4-day forecast by city name (e.g., 杭州市, 北京市).

get_weather_by_city_code

Query real-time weather and 4-day forecast by city administrative code (e.g., 110100).

search_city

Search for cities by name with exact or fuzzy matching; returns matching cities and codes.

get_city_by_adcode

Fetch city information by adcode (e.g., 110000 for Beijing).

list_all_cities

List all available cities with an optional limit (default 50, max 200)