amap-maps

This MCP server provides an interface to the AMap Maps API via the MCP protocol. It enables clients to perform a variety of location-based operations such as geocoding, POI searches, distance calculations, and basic route planning, backed by the AMap Maps service. To use it, configure your MCP-compatible client (e.g., Cursor) to connect to the server using the MCP endpoint implemented by this project. The server requires an AMap Maps API key to access the underlying services. In addition to the MCP endpoint, the project can run a standalone streamable-http protocol server that exposes a simple HTTP interface for streaming data and MCP communication. When enabled, you can access the HTTP API at the configured port and optionally protect it with a token.

Typical usage flow:

• Obtain an AMap Maps API key from the AMap developer portal.
• Start the MCP server with the required API key environment variable.
• In your MCP client, point to the server and perform MCP requests for geocoding, POI searches, or routing as supported by the AMap Maps capabilities.
• If needed, start the streamable-http server (node build/streamable-http.js) and interact via HTTP endpoints such as POST /mcp, optionally securing with HTTP_API_TOKEN.

Prerequisites:

• Node.js (recommended: LTS, v14+)
• npm (comes with Node.js)
• An AMap Maps API key (required)

Step-by-step installation:

1. Install Node.js and npm from https://nodejs.org/
2. Obtain your AMap Maps API key from the AMap developer portal (https://lbs.amap.com/api/webservice/create-project-and-key)
3. Create a configuration file (example json) for the MCP server. You can name it mcp-amap-maps.json:

{ "mcpServers": { "amap-maps": { "command": "npx", "args": ["-y", "@masx200/amap-maps-mcp-server"], "env": { "AMAP_MAPS_API_KEY": "your-amap-maps-api-key" } } } }

4. Run the MCP server using the config:

• If your environment supports automatic config loading (as in the README example), you can start directly with the provided command:

npx -y @masx200/amap-maps-mcp-server

• If you prefer to point to the config file explicitly, ensure your startup script loads the file and passes the env var (AMAP_MAPS_API_KEY) accordingly.

5. Optional: Start the standalone streamable-http server:

node ./build/streamable-http.js

Configure environment variables as needed (see the next section) and access at http://localhost:3000 by default.

Environment variables:

• Required: AMAP_MAPS_API_KEY (your AMap Maps API key)
• Optional: HTTP_API_TOKEN (if set, requests require Authorization: Bearer <token>)
• Optional: HTTP_API_PORT (default 3000 for the standalone streamable-http server)

Tips:

• Keep your API key secure; do not commit it to public repositories.
• The standalone streamable-http server exposes the MCP interface over HTTP; use the Authorization header if HTTP_API_TOKEN is configured.
• If you encounter issues with API key permissions, verify the key is active for the required AMap Maps services (geocoding, POI, routing, etc.).
• The MCP server supports running in environments where npx is available; for production, consider using a persistent process manager to restart on failures.