用 Python 访问高德地图 MCP 服务

一、前置准备

• 在高德开放平台申请 API Key（服务端类型，启用相关服务权限）。

• 确认可用的高德 MCP 服务端地址：

  • SSE：https://mcp.amap.com/sse?key=你的高德APIKey

  • Streamable HTTP：https://mcp.amap.com/mcp?key=你的高德APIKey

• 安装常用依赖（示例使用 SSE 与 LangChain 的 MCP 适配器）：

  • pip 安装：

    • pip install langchain-mcp-adapters python-dotenv[cli]

• 说明：高德官方目前未提供可直接 pip 安装的 MCP Server 包，通常由编辑器/平台托管或使用 npx在本地/容器中拉起服务进程。

二、方式一 通过 SSE 直连高德 MCP（轻量、无本地进程）

• 特点：使用 SSE（Server-Sent Events）长连接，直接连官方托管服务，适合快速调用与调试。

• 示例代码（异步）：

# file: amap_sse.py
import os
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient

# 从环境变量读取密钥：export AMAP_API_KEY=sk-xxxxxx
AMAP_API_KEY = os.getenv("AMAP_API_KEY")
if not AMAP_API_KEY:
    raise ValueError("请设置环境变量 AMAP_API_KEY")

async def main():
    # 连接高德官方托管 MCP（SSE）
    client = MultiServerMCPClient({
        "amap-amap-sse": {
            "url": f"https://mcp.amap.com/sse?key={AMAP_API_KEY}",
            "transport": "sse"
        }
    })

    # 1) 获取服务端提供的工具清单
    tools = await client.get_tools()
    print(f"加载了 {len(tools)} 个工具:")
    for t in tools:
        print(f" - {t.name}: {t.description}")

    # 2) 直接向指定工具发送请求（示例：地理编码）
    tool = client.get_tool_by_name("maps_geo")  # 工具名以实际清单为准
    if not tool:
        raise RuntimeError("未找到工具 maps_geo，请以 tools 列表为准")

    call_id = "demo-geo-001"
    payload = {
        "jsonrpc": "2.0",
        "method": tool.name,
        "params": {"address": "北京市朝阳区望京SOHO"},
        "id": call_id
    }

    # SSE 调用（流式，按事件接收）
    async for event in client.call_tool(tool, payload):
        if event["type"] == "data":
            data = event["data"]
            if "result" in data:
                print("工具结果:", data["result"])
            elif "error" in data:
                print("工具错误:", data["error"])
        elif event["type"] == "done":
            print("调用完成")
            break
        elif event["type"] == "error":
            print("调用异常:", event["error"])
            break

if __name__ == "__main__":
    asyncio.run(main())

• 提示：

  • 工具名与参数以 await client.get_tools()返回的清单为准（常见工具名如：maps_geo、maps_direction、maps_nearby_search等）。

  • 若需“流式中间结果”，SSE 会分事件返回；若仅关心最终结果，可等待 done事件。

三、方式二 本地启动高德 MCP 进程并通过 stdio 调用（便于调试与扩展）

• 特点：在本地或容器中用 npx启动高德 MCP Server，Python 通过 stdio与其通信，便于观察日志、统一网关编排。

• 步骤与代码：

  1. 安装 Node.js（≥ v22.14.0），并确保 npx可用。

  2. 运行 Python 脚本启动本地进程并获取工具：

# file: amap_stdio.py
import os
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient

AMAP_API_KEY = os.getenv("AMAP_API_KEY")
if not AMAP_API_KEY:
    raise ValueError("请设置环境变量 AMAP_API_KEY")

async def main():
    # 本地通过 npx 启动高德 MCP Server（stdio 传输）
    client = MultiServerMCPClient({
        "amap-stdio": {
            "command": "npx",
            "args": ["-y", "@amap/amap-maps-mcp-server"],
            "env": {"AMAP_MAPS_API_KEY": AMAP_API_KEY},
            "transport": "stdio"
        }
    })

    tools = await client.get_tools()
    print(f"加载了 {len(tools)} 个工具:")
    for t in tools:
        print(f" - {t.name}: {t.description}")

    # 示例：调用附近搜索（参数以实际工具清单为准）
    tool = client.get_tool_by_name("maps_nearby_search")
    if not tool:
        raise RuntimeError("未找到工具 maps_nearby_search，请以 tools 列表为准")

    call_id = "demo-nearby-001"
    payload = {
        "jsonrpc": "2.0",
        "method": tool.name,
        "params": {"location": "116.480881,39.989643", "keywords": "美食", "radius": 1000},
        "id": call_id
    }

    async for event in client.call_tool(tool, payload):
        if event["type"] == "data" and "result" in event["data"]:
            print("附近结果:", event["data"]["result"])

if __name__ == "__main__":
    asyncio.run(main())

• 说明：

  • 本地方式便于在 IDE/容器中调试，也可替换为自建 MCP 服务进程（将 command/args 指向你的服务）。

四、在 LangChain/LangGraph 中作为工具使用（推荐）

• 思路：用 MultiServerMCPClient.get_tools()拉取工具列表，传给 create_agent构建智能体，由 LLM 自主编排多步地图能力（如“地点搜索 → 路线规划 → 周边检索”）。

• 示例：

# file: amap_agent.py
import os
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
from langgraph.checkpoint.memory import MemorySaver

AMAP_API_KEY = os.getenv("AMAP_API_KEY")

async def main():
    # 连接高德 MCP（SSE 或 stdio 二选一）
    client = MultiServerMCPClient({
        "amap-amap-sse": {
            "url": f"https://mcp.amap.com/sse?key={AMAP_API_KEY}",
            "transport": "sse"
        }
    })
    tools = await client.get_tools()
    print(f"向智能体注入 {len(tools)} 个 MCP 地图工具")

    llm = ChatOpenAI(
        model="deepseek-ai/DeepSeek-V3.1",
        temperature=0,
        api_key=os.getenv("OPENAI_API_KEY"),
        base_url=os.getenv("OPENAI_BASE_URL")
    )

    agent = create_agent(
        llm,
        tools=tools,
        system_prompt="你是一个高德地图规划助手，能帮我规划行程和获得地图基本信息",
        checkpointer=MemorySaver()
    )

    # 多轮对话示例
    config = {"configurable": {"thread_id": "amap_session_1"}}
    user_input = "北京天安门到故宫怎么走，附近有什么吃的？"
    response = await agent.ainvoke({"messages": [("user", user_input)]}, config=config)
    print("最终回答:", response["messages"][-1].content)

if __name__ == "__main__":
    asyncio.run(main())

• 说明：

  • 该模式可结合记忆、约束、工具中间件等 LangChain 生态能力，构建复杂的多轮地理智能体。

五、常见问题与排查

• 工具列表为空或调用失败

  • 检查 API Key是否有效、是否复制完整；确认 URL/传输方式（SSE 或 stdio）是否正确；在 IDE 中使用前先打开任一工程文件（部分编辑器 MCP 依赖工程上下文）。

• 服务不稳定或超时

  • 优先切换/回退到 SSE 或 Streamable HTTP；SSE/HTTP 任一不通时作为备选路径；查看编辑器/框架的 MCP 工具状态页。

• 参数不匹配

  • 以 get_tools()返回的工具清单为准，严格按 参数名/类型/必填项组装请求；必要时打印工具的输入 Schema 做校验。

• 本地进程方式

  • 确保 Node.js ≥ v22.14.0，并已安装 npx；若权限/网络受限，可改用 Docker 或云端托管 MCP。