1. 为什么要在 Qwen-Agent 里接高德地图 MCPQwen-Agent 是通义千问官方开源的一套 Agent 开发框架它把「大模型 工具调用 多轮对话」这几件事封装成了几个类你只要写几十行 Python 就能跑起来一个能查天气、能算路线、能调外部服务的智能助手。而 MCPModel Context Protocol是 Anthropic 提出的开放协议你可以把它理解成「AI 世界的 USB-C 接口」以前每接一个外部工具你都得手写一套 Function Calling 的 schema、参数校验、返回值解析现在只要有一个符合 MCP 规范的服务端Agent 框架就能自动发现它有哪些工具、每个工具要什么参数然后按需调用。高德地图官方提供了amap/amap-maps-mcp-server这个 Node.js 包里面封装了地点搜索、路径规划、周边推荐等能力。把它挂到 Qwen-Agent 上你就得到了一个能用自然语言问「从浦东机场到外滩怎么走」「南京路附近有什么本帮菜」的地图助手。这套组合适合谁适合想快速验证 Agent 落地场景的开发者、想给自己产品加地图能力的后端同学以及正在学 MCP 协议但缺一个完整可跑案例的人。我试过把整个流程压缩到 10 分钟内完成关键卡点其实不在代码而在 Key 的配置和 MCP 服务的注册方式。下面按「先解决 Key再写配置最后验证」的顺序走一遍。2. TaoToken 统一 Key 的前置准备传统做法里你要分别去阿里云百炼控制台拿 DashScope Key、去高德开放平台拿 Web 服务 Key两个平台两套账号体系调试时还要在环境变量、代码、配置文件之间来回倒腾。TaoToken 的思路是提供一个统一的 API Key 入口把模型调用这一侧的鉴权收敛掉你只需要在 settings.json 和 config.toml 里写一次Qwen-Agent 和后续的 MCP 服务都能复用。具体操作打开 https://taotoken.net/api-keys 登录后创建一个 Key复制出来形如sk-开头的字符串。这个 Key 同时用于模型对话和 Coding Plan 场景如果你后面要跑长期编码任务或 Agent 循环可以在 https://taotoken.net/coding-plan 看套餐说明。模型对话的调试入口在 https://taotoken.net/models 接入文档在 https://taotoken.net/doc 遇到报错先翻文档比搜索引擎快。注意TaoToken 的 API 基址是https://taotoken.net/api不要在后面加 UTM 参数否则部分 SDK 会把 query string 当成路径的一部分导致 404。高德那一侧的 Key 仍然需要你自己去高德开放平台申请「Web 服务」类型的 Key这是地图数据的来源跟模型鉴权是两回事。两个 Key 分别管「谁来思考」和「地图数据从哪来」别混在一个变量里。3. 可复制的 settings.json 与 config.toml 骨架Qwen-Agent 本身不强制你用配置文件但把 Key 和 MCP 服务注册信息抽到外部文件里好处是换环境时不用改代码。下面这份settings.json放在项目根目录Qwen-Agent 启动时会读取{ llm: { model: qwen-max, api_key: sk-你的TaoTokenKey, base_url: https://taotoken.net/api, timeout: 30, retry_count: 3 }, mcpServers: { amap-maps: { command: npx, args: [-y, amap/amap-maps-mcp-server], env: { AMAP_MAPS_API_KEY: 你的高德Web服务Key } } } }对应的config.toml用于那些偏好 TOML 格式的工具链内容等价[llm] model qwen-max api_key sk-你的TaoTokenKey base_url https://taotoken.net/api timeout 30 retry_count 3 [mcpServers.amap-maps] command npx args [-y, amap/amap-maps-mcp-server] [mcpServers.amap-maps.env] AMAP_MAPS_API_KEY 你的高德Web服务Key两个文件二选一即可不要同时存在否则加载顺序不确定。base_url这一行是 TaoToken 统一 Key 生效的关键Qwen-Agent 默认会去 DashScope 的官方地址改成https://taotoken.net/api之后请求才会走统一入口。4. 在 Qwen-Agent 中注册 MCP 服务并跑通一次地图查询先装依赖Python 侧和 Node 侧都要pip install qwen-agent dashscope node -v # 确认 18 npx -v # 确认 npx 可用然后写amap_agent.py核心是把上面 settings.json 里的 mcpServers 段读进来塞给 Assistant 的function_listimport json import os from qwen_agent.agents import Assistant from qwen_agent.gui import WebUI with open(settings.json, r, encodingutf-8) as f: cfg json.load(f) llm_cfg cfg[llm] tools [{mcpServers: cfg[mcpServers]}] def init_agent_service(): system_prompt ( 你扮演一个地图助手具有查询地点、规划路线、推荐周边服务的能力。 回答时先给出结论再补充交通方式和预计耗时。 ) bot Assistant( llmllm_cfg, name地图助手, description地图查询与路线规划, system_messagesystem_prompt, function_listtools, ) print(助手初始化成功) return bot def app_gui(): bot init_agent_service() chatbot_config { prompt.suggestions: [ 帮我规划上海一日游主要想去外滩和迪士尼, 我在南京路步行街找一家评分高的本帮菜, 从浦东机场到外滩怎么走最方便, ] } WebUI(bot, chatbot_configchatbot_config).run() if __name__ __main__: app_gui()跑起来python amap_agent.py浏览器会自动打开http://127.0.0.1:7860。在输入框里敲「帮我查一下上海东方明珠的具体位置和开放时间」观察后台日志Qwen-Agent 会先让模型判断需要调用哪个 MCP 工具然后通过 stdio 把请求发给npx启动的高德 MCP 服务进程拿到坐标和营业时间后再组织成自然语言返回。如果日志里出现tool_call和tool_response两条记录说明 MCP 链路已经通了。5. 本篇常见报错排查报错一npx: command not found或 MCP 服务启动超时。这是 Node 环境没装好或 npx 不在 PATH 里。在终端单独跑npx -y amap/amap-maps-mcp-server如果卡在下载检查 npm registry 是否可达。Qwen-Agent 启动 MCP 子进程时不会继承你 shell 里的全部环境变量所以AMAP_MAPS_API_KEY必须写在 settings.json 的env段里不能只 export 在终端。报错二模型返回 401 或invalid api key。检查base_url是否写成了https://taotoken.net/api末尾不要带斜杠也不要带 UTM 参数。Key 如果是从网页复制时带了空格用strip()处理一下。TaoToken 的 Key 和 DashScope 原生 Key 不通用别拿错。报错三MCP 工具被调用但返回空结果。多半是高德 Key 类型不对。高德开放平台里要选「Web 服务」而不是「Web 端JS API」后者有域名白名单限制服务端调用会被拒。另外高德对同一 Key 有 QPS 限制连续快速提问可能触发限流加个time.sleep(1)在测试循环里。报错四function_list格式错误。Qwen-Agent 要求 MCP 配置包在列表里即[{mcpServers: {...}}]少一层列表或 key 名写成mcp_servers都会导致工具注册失败表现为模型完全不知道有地图工具可用。6. 后续扩展与 Key 管理建议跑通之后你可以把settings.json里的mcpServers段继续加条目比如再挂一个文件系统 MCP 或数据库 MCPQwen-Agent 会自动把所有 MCP 服务的工具合并进同一个 function_list模型按需选择。这就是 MCP 协议的价值加工具不用改 Agent 代码。Key 管理上建议把 TaoToken Key 和高德 Key 都放进.env或系统密钥管理settings.json 里用占位符提交代码前用.gitignore排除。如果你要跑长期的编码 Agent 任务TaoToken 的 Coding Plan 入口在 https://taotoken.net/coding-plan 模型对话调试在 https://taotoken.net/models 接入细节查 https://taotoken.net/doc Key 创建和轮换在 https://taotoken.net/api-keys 。Claude Code 相关的 Anthropic 兼容配置参考 https://taotoken.net/claude-code-anthropic 。最后一个小技巧Qwen-Agent 的 WebUI 支持多轮对话但 MCP 子进程在每次会话结束后不会自动重启。如果你改了高德 Key 或换了 MCP 包版本记得重启 Python 进程否则用的还是旧的环境变量。