1. 从一次“查酒店查到崩溃”说起
如果你正在做 AI Agent 或者智能助手，大概率遇到过这种场景：用户说“帮我找一下杭州西湖附近 3 公里内的酒店，顺便看看明天天气”，你的大模型能理解这句话，但它没法直接访问高德地图的接口。你要么在代码里硬编码一堆 HTTP 请求，要么给每个外部服务写一套适配层，最后代码里全是if service == "amap"这种分支。
MCP（Model Context Protocol）就是来解决这个问题的。你可以把它理解成大模型和外部世界之间的“万能转接头”：大模型负责理解意图，MCP Server 负责把意图翻译成具体 API 调用，两边通过标准协议通信，不用你手写胶水代码。这篇内容面向 Python 开发者，聚焦 MCP 入门和高德地图 API 调用，我会带你跑通酒店查询和天气查询的完整链路，同时用 TaoToken 统一 Key 来管理模型调用凭证，避免在多个平台之间反复切换。
适合谁看：写过 Python、调过 REST API、想把自己的工具接进 AI 工作流但不想被各家 SDK 绑死的开发者。读完你能拿到一份可复制的 MCP 配置骨架、一套 TaoToken 接入方式，以及高德地图请求的验证步骤。
2. TaoToken 前置准备：统一 Key 与 MCP 的关系
在讲 MCP 配置之前，先理清一个容易混淆的点：MCP 解决的是“大模型怎么调工具”，TaoToken 解决的是“大模型本身怎么调”。两者是上下游关系——你的 MCP Server 把高德地图的能力暴露给模型，而模型推理时需要通过一个统一的入口来访问，TaoToken 就是这个入口。
TaoToken 的定位是统一 API 网关，你可以在一个地方管理模型调用凭证，不用为每个模型单独申请 Key。对于 MCP 场景来说，这意味着你的 MCP Host（比如 Claude Desktop、Cursor）在配置模型时，只需要填 TaoToken 的地址和 Key，后续切换模型或者增加工具都不影响已有配置。
具体操作上，你需要先拿到 TaoToken 的 API Key。访问控制台页面（https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite），登录后进入 API Keys 管理页（https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite），创建一个新的 Key 并复制保存。这个 Key 后面会用在 MCP Host 的模型配置里，而不是高德地图的请求里——高德那边你需要单独申请高德开放平台的 Key，两者不要搞混。
如果你还没决定用哪个模型来驱动 MCP 工具调用，可以先在模型对话页面（https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite）测试一下工具调用的效果，确认模型能正确理解“查酒店”和“查天气”这两个意图，再进入后面的配置环节。
3. 可复制配置：MCP Server 骨架与高德 Key 接入
3.1 环境准备与依赖安装
我试过在 Windows 和 macOS 上跑这套流程，Python 版本建议 3.10 以上，因为 MCP 的 Python SDK 用到了较新的异步特性。Node.js 和 npm 不是必须的，但如果你后续想用一些基于 TypeScript 的 MCP Server，装一下会更方便。
先创建一个干净的项目目录，然后初始化虚拟环境：
mkdir mcp-amap-demo && cd mcp-amap-demo python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install uv uv init uv add "mcp[cli]" httpx安装完成后，在终端输入mcp命令，如果能看到帮助信息输出，说明 MCP CLI 已经就绪。这一步很关键，因为后面调试 MCP Server 时会频繁用到这个命令。
3.2 高德地图 API Key 申请
高德开放平台的 Key 申请流程不复杂，但有几个坑要注意。登录高德开放平台后，进入应用管理，创建一个新应用，然后添加 Key。关键点：服务类型一定要选“Web 服务”，不要选“Web 端”或“iOS/Android”，否则后面调 REST API 会报权限错误。
创建完成后复制生成的 Key，建议不要硬编码在代码里，用环境变量管理：
export AMAP_API_KEY="你的高德Key"3.3 MCP Server 代码骨架
在项目根目录创建main.py，写入以下代码。这份骨架同时包含酒店查询和天气查询两个工具，你可以直接复制使用：
import asyncio import os import httpx from mcp.server.fastmcp import FastMCP mcp = FastMCP("gaode-travel-assistant") AMAP_KEY = os.getenv("AMAP_API_KEY", "") @mcp.tool() async def search_hotels_nearby(location: str, radius: int = 3000, keywords: str = "酒店"): """根据经纬度搜索附近酒店，location 格式为 '经度,纬度'""" url = "https://restapi.amap.com/v5/place/around" params = { "key": AMAP_KEY, "location": location, "keywords": keywords, "radius": radius, "types": "住宿服务", "page_size": 10 } timeout = httpx.Timeout(10.0, connect=5.0) async with httpx.AsyncClient(timeout=timeout) as client: try: res = await client.get(url, params=params) res.raise_for_status() data = res.json() if data.get("status") != "1": return {"error": f"高德返回错误: {data.get('info')}"} pois = data.get("pois", []) return [ { "name": p.get("name"), "address": p.get("address"), "distance": p.get("distance"), "tel": p.get("tel") } for p in pois ] except httpx.TimeoutException: return {"error": "请求超时，请检查网络连接"} except httpx.RequestError as e: return {"error": f"请求错误: {str(e)}"} @mcp.tool() async def get_weather(city: str): """根据城市名称查询实时天气，city 为中文城市名如 '杭州'""" url = "https://restapi.amap.com/v3/weather/weatherInfo" params = { "key": AMAP_KEY, "city": city, "extensions": "base" } timeout = httpx.Timeout(10.0, connect=5.0) async with httpx.AsyncClient(timeout=timeout) as client: try: res = await client.get(url, params=params) res.raise_for_status() data = res.json() if data.get("status") != "1": return {"error": f"高德返回错误: {data.get('info')}"} lives = data.get("lives", []) if not lives: return {"error": "未查询到该城市天气数据"} w = lives[0] return { "city": w.get("city"), "weather": w.get("weather"), "temperature": w.get("temperature"), "winddirection": w.get("winddirection"), "windpower": w.get("windpower"), "humidity": w.get("humidity"), "reporttime": w.get("reporttime") } except httpx.TimeoutException: return {"error": "请求超时，请检查网络连接"} except httpx.RequestError as e: return {"error": f"请求错误: {str(e)}"} if __name__ == "__main__": mcp.run(transport="stdio")这段代码里有两个@mcp.tool()装饰的函数，MCP 会自动把它们注册为可调用的工具。大模型在推理时，会根据函数名和 docstring 来判断该调用哪个工具、传什么参数。所以 docstring 一定要写清楚参数格式，比如location是“经度,纬度”而不是“地址”。
3.4 MCP Host 配置
如果你用的是 Claude Desktop 或 Cursor，需要在对应的配置文件中添加这个 MCP Server。以 Claude Desktop 为例，配置文件路径通常是~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或%APPDATA%\Claude\claude_desktop_config.json（Windows）：
{ "mcpServers": { "gaode-travel": { "command": "python", "args": ["/绝对路径/mcp-amap-demo/main.py"], "env": { "AMAP_API_KEY": "你的高德Key" } } } }注意args里要用绝对路径，相对路径在 Host 启动子进程时容易找不到文件。保存后重启 Host，在工具列表里应该能看到search_hotels_nearby和get_weather两个工具。
4. 验证请求：从配置到查询的闭环
4.1 先用 MCP CLI 本地验证
在接入 Host 之前，建议先用 MCP CLI 确认 Server 本身能正常工作：
mcp dev main.py这会启动一个开发模式的服务，你可以在终端里手动调用工具。比如输入工具名get_weather，参数{"city": "杭州"}，如果返回类似下面的结构，说明高德 API 调用链路是通的：
{ "city": "杭州市", "weather": "晴", "temperature": "28", "winddirection": "东南", "windpower": "≤3", "humidity": "65", "reporttime": "2025-01-15 14:00:00" }酒店查询需要先拿到经纬度。你可以用高德的地理编码接口先查“杭州西湖”的坐标，或者直接用一个已知坐标测试，比如120.153,30.287（西湖附近）：
# 在 mcp dev 交互界面中调用 search_hotels_nearby(location="120.153,30.287", radius=2000)返回结果应该是一个列表，包含酒店名称、地址、距离和电话。如果返回{"error": "..."}，先检查高德 Key 是否有效、服务类型是否选对。
4.2 在 Host 中验证工具调用
重启 Claude Desktop 或 Cursor 后，在对话里输入：“帮我查一下杭州现在的天气，然后找一下西湖附近 2 公里的酒店。” 观察模型是否自动调用了两个工具。正常情况下，你会看到工具调用卡片依次展开，先返回天气数据，再返回酒店列表，最后模型用自然语言总结。
如果模型没有调用工具，而是直接编造答案，说明 MCP Server 没有正确注册。检查 Host 的日志（Claude Desktop 的日志在~/Library/Logs/Claude/），看是否有MCP server failed to start之类的错误。
4.3 用 TaoToken 统一管理模型调用
当你的 MCP 工具越来越多，可能会遇到模型切换的问题：今天用 Claude 调工具，明天想换成 GPT 试试效果，每次都要改配置。TaoToken 的 Coding Plan（https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite）支持在同一个入口下切换模型，MCP Host 的配置只需要指向 TaoToken 的 API 地址（https://taotoken.net/api），Key 也只用填一次。
对于长期跑 Agent 的场景，建议把模型调用和工具调用分开管理：MCP Server 负责工具执行，TaoToken 负责模型推理。这样调试的时候可以单独替换某一层，不用整体重构。
5. 本篇常见错排查
5.1 高德返回INVALID_USER_KEY或USERKEY_PLAT_NOMATCH
这是最常见的问题，90% 的情况是 Key 的服务类型选错了。高德开放平台创建 Key 时，如果你选了“Web 端”或“iOS”，调 REST API 就会报这个错。解决办法：回到应用管理，重新创建一个 Key，服务类型选“Web 服务”。
另一个可能是 Key 没有绑定正确的应用，或者应用被删除了。检查 Key 列表里的“绑定服务”是否包含“Web 服务 API”。
5.2 MCP Server 启动失败，Host 里看不到工具
先确认python命令在 Host 的环境变量里能直接执行。有些系统里 Python 装在了 conda 环境或 pyenv 里，Host 启动子进程时找不到。解决办法：在配置文件的command字段里写 Python 的绝对路径，比如/Users/yourname/.venv/bin/python。
如果 Host 日志显示ModuleNotFoundError: No module named 'mcp'，说明虚拟环境没有激活，或者依赖装到了全局环境。在args里加上-u参数可以避免缓冲问题，但根本解决方法是确保command指向的 Python 解释器里装了mcp包。
5.3 工具调用超时或返回空结果
高德 API 有 QPS 限制，免费 Key 的并发能力有限。如果你在短时间内连续调用多次，可能会被限流。建议在代码里加一个简单的重试逻辑，或者把radius参数调小，减少返回数据量。
另外，location参数的格式必须是“经度,纬度”，顺序不能反。我踩过的坑：把纬度写在前面，结果查到了南极洲附近的酒店（当然是空的）。如果你不确定坐标，先用高德的地理编码接口把地址转成坐标。
5.4 模型不调用工具，直接编造答案
这种情况通常是因为工具的 docstring 写得太模糊，模型无法判断什么时候该调用。比如search_hotels_nearby的 docstring 如果只写“搜索酒店”，模型可能觉得它和普通对话没区别。改成“根据经纬度搜索附近酒店，location 格式为 '经度,纬度'”之后，模型就能正确识别参数格式。
如果还是不行，检查 Host 的模型是否支持工具调用。部分轻量模型对 function calling 的支持不完整，换一个能力更强的模型试试。你可以在 TaoToken 的模型对话页面快速切换模型做对比测试。
6. 把 MCP 工具接进你的日常工作流
跑通酒店查询和天气查询之后，你可以用同样的骨架接入更多高德能力：路径规划、地理编码、交通态势。核心思路是一样的——用@mcp.tool()装饰一个异步函数，在函数里调高德 REST API，返回结构化数据。
如果你想让 MCP Server 在团队里共享，可以考虑把它部署成一个独立的 SSE 服务，而不是本地 stdio 进程。高德官方也提供了 MCP Server 的 SSE 端点，你可以参考它的实现方式来设计自己的服务。
最后提醒一点：MCP 工具函数的返回值尽量保持结构化，不要返回大段自然语言。让模型自己根据结构化数据生成回答，这样可控性更强，也方便你在中间加一层数据校验。如果你在接入过程中遇到工具注册或模型调用的问题，可以到 TaoToken 的接入文档（https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite）里查一下配置示例，或者直接在模型对话里贴上报错信息让模型帮你分析。
