Build

You will run a Gaode Map (AMAP) based MCP service that enables clients to perform location-based actions such as IP定位 and nearby searches. This MCP server centralizes configuration, logging, and the Gaode Map SDK usage so your client applications can query geolocation data and nearby points of interest through a consistent interface.

How to use

You can connect your MCP client to this server in two ways: a local stdio-based MCP server or a streamable-http MCP server that exposes an HTTP interface. For the stdio approach, you start the MCP process locally and connect to it via the standard input/output transport. For the HTTP approach, you run the server with a streamable-http transport and consume it over HTTP on localhost:8000. In both cases, you can perform Gaode Map API based operations such as IP定位 and nearby searches through the MCP API surface exposed by the server.

Practical usage patterns include: configuring the server with your Gaode API key, starting the local MCP process during your app's startup, and then pointing your MCP client to either the local stdio runner or the local HTTP endpoint. Ensure your API key is kept secure and that you handle any rate limits or retries according to your application's needs.

How to install

Prerequisites you need on your machine before starting: a supported Python environment and the UV runtime tool. You will create a project, install dependencies, and prepare a configuration for the Gaode API.

# Install UV (example for Windows, Linux, or macOS varies by shell)
# Linux or macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Create the MCP project with UV, enter the project directory, and set up a virtual environment. Then install the required MCP tools and dependencies.

uv init build-mcp
cd build-mcp

uv venv
source .venv/Scripts/activate

uv add mcp[cli] httpx pytest

Place the Gaode API and server configuration in a YAML file at the expected location, including your API key, base URL, retry settings, and log configuration.

# src/build_mcp/config.yaml
api_key: test
base_url: https://restapi.amap.com
proxy: 
log_level: INFO
max_retries: 5
retry_delay: 1
backoff_factor: 2
log_dir: /var/log/build_mcp

Install the editable package so changes you make during development take effect immediately.

uv pip install -e .

Run the MCP service using the stdio transport to start the local server, or use the streamable-http transport for HTTP access.

# Start stdio MCP service
uv run build_mcp

# Start streamable-http MCP service
uv run build_mcp streamable-http

Additional configuration and notes

You can test and debug the service using Inspector, a local web UI that lets you call the MCP tools directly. This makes it easy to verify API behavior without writing client code.

When configuring MCP connections for clients, you can choose either the stdio configuration or the HTTP configuration. For the stdio setup, provide the command and arguments to launch the local process and specify any needed environment variables. For the HTTP setup, provide the local HTTP endpoint URL where the MCP server is exposed.

Below is an example MCP client configuration for the stdio approach, which includes the command to run the server and an environment variable placeholder for your Gaode API key.

{
  "mcpServers": {
    "build_mcp": {
      "command": "uv",
      "args": [
        "run",
        "-m",
        "build_mcp"
      ],
      "env": {
        "API_KEY": "YOUR_AMAP_API_KEY"
      }
    }
  }
}

You can also run the HTTP-based MCP server, which serves an API at http://localhost:8000/mcp. The corresponding client configuration points to that URL.

{
  "mcpServers": {
    "build_mcp_http": {
      "url": "http://localhost:8000/mcp",
      "type": "http",
      "args": []
    }
  }
}

Available tools

Inspector

Debug and test MCP services through a local web UI that lets you call MCP tools directly.