MCP 实战指南：高德地图和 arXiv API 封装指导教程

原创

于 2025-08-22 10:41:07 发布 · 730 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能

本文是 MCP（Model Context Protocol）教程系列的第二阶段，我们将告别理论，直接进入开发实战。你将学会如何把第三方 API快速封装成 Claude 等 AI 模型可直接调用的强大工具。我们将以高德地图地理编码和arXiv 论文检索这两个实用场景为例，内容涵盖资源定义、工具实现、错误处理等核心开发环节，带你一步步完成从零到可用的工具集成。

一、项目初始化与环境搭建

首先，确保你已准备好开发环境。我们推荐使用 Python，因为其生态拥有最完善的 MCP 支持。

创建项目目录：
```
mkdir my-mcp-server
cd my-mcp-server
```

创建虚拟环境并激活：

python -m venv venv
# On Windows
.\venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

安装核心依赖： MCP 的核心是 mcp 库，此外我们还需要用于 HTTP 请求的 aiohttp 和用于管理异步并发的 anyio。
```
pip install mcp aiohttp anyio
```
创建主文件：
```
touch server.py
```

二、MCP 服务器骨架：起点

每个 MCP Server 都需要一个基本的程序结构。我们在 server.py 中搭建骨架。

import asyncio
from mcp.server import Server
from mcp.server.stdio import stdio_server

# 创建 Server 实例，名字叫 "my-custom-tools"
app = Server("my-custom-tools")

# 此处将在这里注册我们的工具（Tools）和资源（Resources）

asyncdef main():
    # 使用 stdio 传输层，这是与 Claude 等客户端通信的标准方式
    asyncwith stdio_server() as (read_stream, write_stream):
        await app.run(
            read_stream,
            write_stream,
            app.create_initialization_options()
        )

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

现在，你可以运行 python server.py，虽然它还做不了任何事情，但骨架已经搭好。接下来我们为其注入灵魂。

三、实战一：封装高德地图地理编码 API（Tools）

我们将把高德地图的“地理编码”API 封装成一个 MCP Tool，让 Claude 能够根据地址查询经纬度。

1. 获取 API Key

前往高德开放平台，注册账号并创建一个新应用，获取你的 API Key（your_amap_api_key_here）。

2. 声明并实现工具

我们在 app 实例上使用 @app.tool() 装饰器来声明一个工具。

import aiohttp
from mcp.server.models import ToolResult
from mcp.types import Tool

# 你的高德 API Key，在实际项目中应从环境变量读取！
AMAP_API_KEY = "your_amap_api_key_here"

@app.tool()
asyncdef geocode_address(address: str) -> Tool:
    """根据中文地址获取其经纬度坐标。

    Args:
        address: 详细的中文地址，例如：北京市朝阳区阜通东大街6号。

    Returns:
        返回该地址的经纬度信息。
    """
    # 构建请求 URL
    url = f"https://restapi.amap.com/v3/geocode/geo?key={AMAP_API_KEY}&address={address}"

    # 错误处理与超时控制：使用 aiohttp 和 asyncio.timeout
    try:
        asyncwith aiohttp.ClientSession() as session:
            # 设置 10 秒超时
            asyncwith asyncio.timeout(10):
                asyncwith session.get(url) as response:
                    # 检查 HTTP 状态码是否成功
                    response.raise_for_status()
          &nb