Python 实现 MCP 客户端调用高德地图天气查询示例

MCP 协议简介与架构

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

核心架构

理解架构有助于我们更好地编写客户端代码：

• MCP 主机：希望访问数据的程序，例如 Claude Desktop、IDE 或各类 AI 工具。
• MCP 客户端：负责与服务器保持 1:1 连接的协议客户端。
• MCP 服务器：轻量级程序，通过标准化协议公开特定功能。
• 数据源：包括本地文件、数据库以及通过互联网 API 连接的外部系统。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

1. Node.js 版本：建议 >= 18.20.4。版本过低可能导致 npx 命令执行异常。
2. 高德地图 API Key：你需要申请 AMAP_MAPS_API_KEY。具体文档可参考 高德地图 MCP 服务文档。

Python 客户端实战

使用 Python SDK 是最直接的集成方式。首先安装依赖：

pip install mcp

下面是一个完整的异步调用示例。这段代码展示了如何启动 npx 进程作为服务端，并通过 stdio 传输层建立会话。

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": "your_api_key_here"}  # 替换为你的实际 Key
)

async def run():
    # 建立 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())

关键点说明：

• 这里使用了 StdioServerParameters 来指定 npx 命令，这是 MCP 官方推荐的运行方式之一。
• env 字典用于传递敏感信息（如 API Key），避免硬编码在代码中。
• 整个流程是异步的，利用 asyncio 处理 IO 操作，避免阻塞主线程。

Java 客户端参考

如果你更习惯 Java 生态，也可以参考官方提供的 SDK。以下是基于 Maven 的依赖引入及测试用例示例：

Maven 依赖：

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

代码示例：

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.spec.McpSchema;
import org.junit.jupiter.api.Test;
import java.util.Map;

public class JunitTest {
    @Test
    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());
    }
}

Java 版本提供了同步客户端 McpSyncClient，对于不需要复杂异步处理的场景更为友好。注意查看官方迁移指南以适配不同版本的 API 变化。

官方资源

• MCP 官网
• Python SDK GitHub
• Java SDK GitHub