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

MCP 协议简介与架构

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

在典型的 MCP 架构中，主要包含以下几个角色：

• MCP 主机：希望访问数据的程序，比如 IDE、Claude Desktop 或其他 AI 工具。
• MCP 客户端：负责与服务器建立 1:1 连接的协议客户端。
• MCP 服务器：轻量级程序，通过标准协议公开特定功能（如高德地图的天气查询）。
• 数据源：包括本地文件、数据库或远程 API 服务。

环境准备

要运行高德地图的 MCP 服务，首先需要确保你的开发环境满足以下要求。

Node.js 版本

服务端通常通过 npx 命令启动，因此需要 Node.js 环境。建议版本不低于 18.20.4，旧版本可能无法正确执行相关命令。

获取 API Key

你需要申请高德地图的 AMAP_MAPS_API_KEY。具体文档可参考高德官方说明，确保拥有调用天气接口所需的权限。

Python SDK 实现

既然我们要用 Python 来构建客户端，第一步是安装官方 SDK。

pip install mcp

安装完成后，核心逻辑在于配置 StdioServerParameters 并建立会话。下面是一个完整的异步调用示例，我们通过它来查询福州的天气。

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

async def run():
    # 配置服务端参数
    # 这里使用 npx 启动高德地图的 MCP 服务容器
    server_params = StdioServerParameters(
        command="npx",
        args=["-y", "@amap/amap-maps-mcp-server"],
        env={"AMAP_MAPS_API_KEY": "your_api_key_here"}  # 替换为你的实际 Key
    )

    # 建立stdio通信通道
    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())

代码关键点解析

1. 异步编程：MCP 客户端基于异步 IO，所以必须使用 async/await 模式。asyncio.run() 用于启动事件循环。
2. 环境变量传递：API Key 敏感信息不应硬编码在代码里，而是通过 env 字典传递给子进程，这样更安全。
3. 工具调用：call_tool 方法接收工具名称和参数字典。高德地图提供了 maps_weather 等工具，参数需符合其 Schema 定义。

Java SDK 参考

如果你更习惯使用 Java，官方也提供了对应的 SDK。虽然本文重点在 Python，但 Java 的实现思路类似，都是基于 McpClient 进行同步或异步调用。

引入依赖（Maven）：

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

核心调用逻辑如下：

import io.modelcontextprotocol.client.McpSyncClient;
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", "your_api_key_here")
            .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());
    }
}

在实际集成时，注意处理异常情况和网络超时问题。MCP 的设计初衷就是让 AI 应用能像调用普通函数一样调用外部服务，理解这一层抽象后，扩展其他服务也会变得简单。