Amap (Gaode Maps) MCP Server

如何从零开始构建一个高德地图的MCP服务，涵盖了以下内容：

MCP服务的基本概念和配置

如何使用高德地图API进行IP定位和周边搜索

如何编写MCP服务的核心功能，包括配置管理、日志系统和高德地图SDK

如何编写MCP服务的主程序和入口

如何调试MCP服务，包括使用Inspector和编写测试代码

如何使用Makefile管理项目命令

如何配置MCP客户端连接到我们的服务

配置开发环境

⚠ 请务必根据自己的操作系统调整命令，powershell 和 bash 的命令语法有所不同。

作者使用的是windows+git终端。 本教程前半段与官方基本无异，可查考官方文档中server开发示例。

安装UV

# 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"

创建虚拟环境初始化项目

# 使用UV创建并进入项目目录
uv init build-mcp
cd build-mcp

# 创建虚拟环境
uv venv
source .venv/Scripts/activate

# 安装相关依赖
uv add mcp[cli] httpx pytest

在 src/build_mcp/config.yaml 文件中添加以下内容：

# 高德地图API配置
api_key: test
# 高德地图API的基础URL
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

⚠ config.yaml 文件需要放在 src/build_mcp/ 目录下，这样在加载配置时可以正确找到。

安装代码

⚠ 首次安装代码时需要使用 pip install -e . 命令，这样可以将当前目录作为一个可编辑的包安装到虚拟环境中。这样在开发过程中对代码的修改会立即生效，无需重新安装。

uv pip install -e .

通过以下命令来运行 MCP 服务：

启动stdio协议的MCP服务：

uv run build_mcp

启动streamable-http协议的MCP服务：

uv run build_mcp streamable-http

2.使用Inspector进行测试

Inspector是官方提供的一个MCP服务调试工具，可以通过它来启动一个本地web界面，在界面中可以直接调用MCP服务的工具。 相对更加直观和易用，比较推荐这种方式，详情可以查看官方文档。

# 使用Inspector调试stdio协议的MCP服务
API_KEY=你的KEY mcp dev src/build_mcp/__init__.py

如何使用这个MCP服务？

首先你得拥有一个MCP客户端，目前市场上各种类型得MCP客户端层出不穷，至于用什么全凭你的爱好了。

这里有一份非常详细的MCP客户端使用攻略，是github上一个非常棒的项目：MCP客户端使用攻略

选择一个客户端下载安装，然后我们对我们开发的服务进行配置。

配置Stdio协议的MCP服务

{
    "mcpServers": {
        "build_mcp": {
            "command": "uv",
            "args": [
                "run",
                "-m"
                "build_mcp"
            ],
            "env": {
                "API_KEY": "你的高德API Key"
            }
        }
    }
}

⚠ 要注意本地UV环境，如果安装了多个UV可能会导致环境混乱，这是开发过程中比较头疼的一点，要自己注意。

配置Streamable-HTTP协议的MCP服务

启动项目

make streamable-http

$ make streamable-http
Starting MCP service with streamable-http protocol...
uv run build_mcp streamable-http

INFO: 🚀 Starting MCP server with transport type: streamable-http
INFO:     Started server process [6064]
INFO:     Waiting for application startup.
INFO:    StreamableHTTP session manager started                                                                                                                                     streamable_http_manager.py:109
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

启动成功后会在8000端口启动一个HTTP服务。

客户端配置

{
    "mcpServers": {
        "build_mcp_http": {
            "url": "http://localhost:8000/mcp"
        }
    }
}