Python 调用高德地图 MCP 服务查询天气示例

MCP（Model Context Protocol）是一种开放协议，它标准化了应用程序向 LLM 提供上下文的方式。你可以把它理解为 AI 应用的 USB-C 端口——就像 USB-C 让设备能连接各种外设一样，MCP 让 AI 模型能标准化地连接不同的数据源和工具。

MCP 架构简析

在接入高德地图服务之前，先简单过一下核心组件：

MCP 主机：希望访问数据的程序，比如 Claude Desktop、IDE 或 AI 工具。
MCP 客户端：与服务器保持 1:1 连接的协议客户端。
MCP 服务器：轻量级程序，通过标准协议公开特定功能。
本地/远程数据源：服务器可安全访问的文件、数据库或外部 API。

环境准备

要运行高德地图的 MCP 服务器，我们需要 Node.js 环境。请确保版本不低于 18.20.4，否则 npx 命令可能无法正常工作。

获取高德地图 API Key 是必要步骤，文档地址如下：高德地图 MCP 服务文档

准备好后，我们可以查看一下高德 MCP 服务提供的工具列表。以天气查询为例，其输入 schema 包含城市名称或 adcode：

{
  "tools": [
    {
      "name": "maps_weather",
      "description": "根据城市名称或者标准 adcode 查询指定城市的天气",
      "inputSchema": {
        "properties": {
          "city": {"type": "string", "description": "城市名称或者 adcode"}
        },
        "required": ["city"],
        "type": "object"
      }
    }
  ]
}

Python 客户端实现

我们使用官方 Python SDK 来构建客户端。首先安装依赖：

pip install mcp

接下来是核心代码。这里采用 StdioServerParameters 启动本地进程作为服务器，并通过 ClientSession 进行交互。注意环境变量中需要填入你的 AMAP_MAPS_API_KEY。

import asyncio
from mcp import ClientSession, StdioServerParameters, types
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@amap/amap-maps-mcp-server"],
    env={"AMAP_MAPS_API_KEY": "xxxxx"}  # 替换为你的实际 Key
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # 列出可用工具
            tools = await session.list_tools()
            print("工具列表:", tools)
            
            # 调用天气查询工具
            result = await session.call_tool(
                "maps_weather", 
                arguments={"city": "福州"}
            )
            print("调用结果:", result)

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

运行这段脚本，你会看到初始化成功后的工具列表，以及针对'福州'返回的天气数据。这种异步结构非常适合集成到现有的 AI Agent 工作流中。

Java 客户端参考

如果你更习惯 Java 生态，官方也提供了对应的 SDK。目前推荐使用 0.8.1 版本。

Maven 依赖

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
    <version>0.8.1</version>
</dependency>

Gradle 依赖

implementation("io.modelcontextprotocol.sdk:mcp:0.8.1")

代码示例

Java 端主要使用 McpSyncClient 进行同步调用，逻辑与 Python 类似：

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.spec.McpSchema;

public class JunitTest {
    public void test() {
        ServerParameters params = ServerParameters.builder("npx")
            .args("-y", "@amap/amap-maps-mcp-server")
            .addEnvVar("AMAP_MAPS_API_KEY", "xxxxx")
            .build();
            
        StdioClientTransport transport = new StdioClientTransport(params);
        McpSyncClient client = McpClient.sync(transport).build();
        
        client.initialize();
        McpSchema.ListToolsResult toolsList = client.listTools();
        System.out.println("工具列表:" + toolsList);
        
        McpSchema.CallToolResult mapsWeather = client.callTool(
            new McpSchema.CallToolRequest("maps_weather", Map.of("city", "福州"))
        );
        System.out.println("调用结果:" + mapsWeather.content());
    }
}

参考资料