1. 为什么要在 CodeBuddy 里接百度地图 MCP如果你正在用 CodeBuddy 写代码同时又想让 AI 直接帮你查地址、算路线、搜周边那百度地图 MCP 就是最省事的一条路。MCP 全称 Model Context Protocol你可以把它理解成给 AI 装的一个「外挂工具箱」——AI 本身不会查地图但通过 MCP 协议挂上百度地图的服务端它就能调用地理编码、POI 搜索、路线规划这些真实接口。百度地图 MCP 能做什么简单说它把百度地图开放平台的 10 个标准接口封装成了 AI 可以直接调用的工具包括地址转坐标、坐标反查地址、关键词搜周边、两点路线规划、批量路线矩阵、实时天气、IP 定位、道路交通状况等。适合谁适合所有在 CodeBuddy 里做 LBS 相关开发的人——比如你要做一个「附近咖啡店」功能或者需要批量把地址转成经纬度又或者想让 AI 帮你规划配送路线。我试过在 CodeBuddy 里从零接入这套东西整个过程其实不复杂但有几个坑特别容易踩变量名配错、IP 白名单没加、改完配置没重启。这篇就把从 mcp.json 骨架到 API Key 验证的完整路径拆开讲你跟着做一遍就能在本地跑通。在开始之前先明确一个思路CodeBuddy 负责「调用方」百度地图 MCP Server 负责「执行方」而 API Key 是两者之间的通行证。通行证对了配置对了重启生效了就能跑通。下面按这个顺序来。2. 前置准备百度地图 AK 与 TaoToken 通道2.1 申请百度地图 API KeyAK打开百度地图开放平台控制台注册或登录后创建一个应用。这里有个关键点应用类型必须选「服务端」不要选浏览器端或 iOS/Android 端因为 MCP Server 是在服务端发请求的。创建完成后你会拿到一个 AKAPI Key。拿到之后还有一步容易漏在应用里启用「MCP (SSE)」服务。如果不启用调用可能直接失败或者性能很差。这一步在控制台的服务勾选里能找到。AK 是敏感凭证明文写在 mcp.json 里所以千万别把它提交到 git 仓库。建议本地用 .gitignore 把 .codebuddy 目录排除掉或者用环境变量注入的方式管理。2.2 TaoToken 统一 Key/API 通道的接入位置如果你同时在用多个模型或工具管理一堆 Key 会很烦。TaoToken 提供了一条统一的 API 通道官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。在 CodeBuddy 里接入百度地图 MCP 的场景下TaoToken 的作用是帮你统一管理模型侧的 Key。也就是说百度地图的 AK 归百度地图管模型调用的 Key 归 TaoToken 管两者不冲突。你可以在 TaoToken 的 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 生成一个 Key然后在 CodeBuddy 的模型配置里填上。具体来说CodeBuddy 的模型配置里需要填三件套Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api API Key 填你在 TaoToken 生成的 KeyModel ID 按你实际用的模型填。这样模型对话走 TaoToken 通道百度地图 MCP 走百度地图 AK各管各的互不影响。如果你还没决定用哪个模型可以先到模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试一下确认通道通了再往下配。2.3 确认 Node.js 环境百度地图 MCP Server 的 Node 版包名是 baidumap/mcp-server-baidu-map通过 npx 拉起。所以你需要本地有 Node.js 环境。实测 Node 22 没问题其他 LTS 版本也可以。装好后在终端跑一下 node -v 确认版本。如果你更习惯 Python也有对应的包 mcp-server-baidu-maps但要注意环境变量名不一样后面会专门讲这个坑。3. 可复制配置mcp.json 骨架与参数对照3.1 mcp.json 文件位置CodeBuddy 的 MCP 配置文件在用户目录下的 .codebuddy 文件夹里。Windows 上是 C:\Users\你的用户名.codebuddy\mcp.jsonmacOS/Linux 上是 ~/.codebuddy/mcp.json。如果文件不存在就新建一个。3.2 完整可复制的 mcp.json 片段在 mcpServers 对象里追加下面这段。注意把 你的AK 替换成你实际申请到的百度地图 API Key{ mcpServers: { baidu-map: { command: D:/SoftWare/node22/npx.cmd, args: [-y, baidumap/mcp-server-baidu-map], env: { BAIDU_MAP_API_KEY: 你的AK }, description: 百度地图LBS服务地理编码/POI/路线/天气/交通, disabled: false } } }几个参数说明一下。command 指向你本地的 npx 可执行文件路径Windows 上是 npx.cmdmacOS/Linux 上通常是 /usr/local/bin/npx 或直接写 npx。args 里的 -y 表示自动确认安装baidumap/mcp-server-baidu-map 是包名。env 里放 API Key。description 是给 AI 看的工具描述写清楚点有助于模型判断什么时候调用。disabled 设为 false 表示启用。3.3 Node 版与 Python 版参数对照这里是最容易踩的坑两个版本的环境变量名不一样接入方式包名环境变量名Node.js推荐baidumap/mcp-server-baidu-mapBAIDU_MAP_API_KEY无 SPythonmcp-server-baidu-mapsBAIDU_MAPS_API_KEY有 SNode 版用 BAIDU_MAP_API_KEYPython 版才用 BAIDU_MAPS_API_KEY。配错的话鉴权会直接失败而且报错信息不一定明确指向变量名排查起来很费时间。建议直接用 Node 版生态更成熟npx 拉起也方便。3.4 生效方式写完 mcp.json 后配置不会自动生效。你需要在 CodeBuddy 里对这个 MCP 做一次「禁用 → 启用」操作或者直接重启 CodeBuddy。实测下来禁用再启用比重启快推荐用这个方式。3.5 工具清单速查配置生效后这个 MCP 会暴露 10 个工具工具作用map_geocode地址 → 经纬度坐标map_reverse_geocode坐标 → 地址/区域/周边 POImap_search_places按关键词/类型/半径搜 POImap_place_details按 POI 唯一 ID 取详情map_directions两点路线规划驾车/步行/骑行/公交map_directions_matrix批量路线矩阵多起点→多终点map_weather按区域/坐标查实时 预报天气map_ip_location通过 IP 定位城市 坐标map_road_traffic查道路/区域实时交通状况map_poi_extract从自由文本提取 POI需高级权限经典三件套 map_geocode map_search_places map_directions 就能覆盖绝大多数 LBS 场景。4. 验证请求从地址转坐标到搜周边咖啡店4.1 第一步地理编码验证配置生效后在 CodeBuddy 的对话里直接让 AI 调用 map_geocode输入「北京市海淀区中关村大街」。如果一切正常你会拿到类似这样的返回经度 (lng)116.324104 纬度 (lat)39.981942 解析级别道路level道路这一步能跑通说明 AK 有效、MCP 连接正常、网络可达。如果这里就报错先去看第 5 节的排查。4.2 第二步检索周边咖啡店拿到坐标后调用 map_search_places中心点填 39.98194156690778,116.32410398706402关键词填「咖啡」。这里有个细节要注意该 MCP 的 search_places 没有暴露 radius 参数所以返回结果可能超出你想要的半径。解决办法是对返回结果用 Haversine 公式算直线距离再过滤出 2km 以内的。实测返回结果共 10 家按由近及远#名称距中心地址1书和咖啡~61 m海淀区中关村大街31号2瑞幸咖啡(海淀剧院店)~139 m中关村大街28号-1号一层3OKCOFFEE福气咖啡(海淀文化艺术大厦店)~211 m中关村大街甲28号海淀文化艺术大厦B座7层4弄咖啡 GNU COFFEE(银网中心店)~270 m知春路113号银网中心-B座F15MANNER COFFEE(新中关购物中心店)~316 m中关村大街19号新中关大厦KL1056MaoCafe猫叔咖啡(人民大学店)~445 m人民大学北路静园7号楼1层7瑞幸咖啡(互联网金融中心店)~534 m丹棱街1号互联网金融中心一层大堂8瑞幸咖啡(科学院南路店)~632 m中关村科学院南路17号一层罗森9MOJO(中关村店)~666 m中关村大街11号e世界财富中心A座底商10瑞幸咖啡(四通大厦店)~721 m海淀大街2号四通大厦一层大堂距离是直线估算实际步行或驾车距离会更长。坐标来自百度 POI 数据可能和门牌有微小偏差这是正常的。4.3 第三步路线规划验证再调一次 map_directions起点填中关村大街终点填你搜到的某家咖啡店出行方式选步行。返回会包含距离、预计时间和路径点。这一步能跑通说明路线规划接口也正常。三步都跑通基本可以确认整个链路没问题了。如果某一步失败对照下面的排查表。5. 本篇常见错排查5.1 APP IP校验失败现象首次调用 map_geocode 返回 Geocoding failed: APP IP校验失败。根因该 AK 在开放平台开启了「IP 白名单」校验当前机器发起请求的出口 IP 不在白名单里被服务端拒绝。注意请求能到达百度服务器说明机器本身能联网问题只在白名单。正确解法查当前公网出口 IP然后打开百度地图开放平台控制台找到该 AK 对应的应用 → 编辑 → IP 白名单把出口 IP 加进去。临时调试可以填 0.0.0.0/0 放开所有 IP但用完记得改回来。保存后直接重跑即可无需重启 MCP。如果以后又报这个错多半是公网 IP 变了动态分配重新查 IP 再加一次白名单就行。5.2 SN 校验方案不可行有人会想改用 AK SK 的 SN 签名模式来绕过 IP 白名单。这条路走不通。查官方仓库baidu-maps/mcp可以确认该 MCP Server 只支持 AK 鉴权没有任何 SK / SN 签名的环境变量也不会自己算签名。即使你在开放平台把 AK 类型改为 SN 校验MCP 发出的请求不带 sn 参数百度照样拒绝。结论对 MCP 唯一友好的是 IP 白名单模式SN 方案不成立别在这上面浪费时间。5.3 变量名配错导致鉴权失败现象MCP 能启动但调用工具时报鉴权失败或 401。排查检查 mcp.json 里的环境变量名。Node 版必须是 BAIDU_MAP_API_KEYPython 版才是 BAIDU_MAPS_API_KEY。如果你用的是 Node 版却写了带 S 的变量名Server 读不到 Key自然鉴权失败。5.4 改完配置没生效现象改了 mcp.json但调用行为没变化。原因MCP 配置不会热加载。需要在 CodeBuddy 里对该 MCP 做一次禁用 → 启用或者重启 CodeBuddy。实测禁用再启用更快。5.5 local proxy failed 或连接超时现象调用时报 local proxy failed 或连接超时。排查方向先确认 npx 路径是否正确command 指向的可执行文件是否存在。再确认网络能正常访问百度地图开放平台。如果公司网络有出口限制可能需要联系网络管理员放行。5.6 reading choices 类报错现象返回结果解析时报 reading choices 相关错误。这类错误通常出现在模型侧返回格式异常时。检查 CodeBuddy 的模型配置三件套是否完整Base URL 填 https://taotoken.net/api API Key 填 TaoToken 生成的 KeyModel ID 填你实际使用的模型。三者缺一不可。如果模型通道本身有问题先到模型对话页面验证一下通道是否正常。5.7 OAuth 相关报错如果你在 CodeBuddy 里同时配了需要 OAuth 的 MCP可能会遇到 OAuth 回调失败。这类问题和百度地图 MCP 无关是另一个 MCP 的鉴权流程问题。排查时先确认报错来自哪个 MCP再针对性处理。百度地图 MCP 用的是 AK 鉴权不涉及 OAuth。6. 跑通之后把百度地图 MCP 用起来配置跑通只是第一步真正有价值的是把它用起来。几个实用方向第一把 map_geocode 和 map_search_places 组合起来做「地址周边搜索」。用户给一个地址你先转坐标再搜周边一套流程下来就能返回结构化结果。第二用 map_directions_matrix 做批量路线规划。比如你有多个起点和多个终点想算所有组合的距离这个接口一次就能返回矩阵比循环调用 map_directions 快得多。第三map_weather 和 map_road_traffic 可以叠加到路线规划上做「天气 路况 路线」的综合决策。比如下雨天优先推荐步行距离短的路线。如果你要长期在 CodeBuddy 里做编码和 Agent 相关的工作可以考虑用 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 把模型调用和工具链统一管理起来。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。最后提醒一句AK 别提交到 gitIP 白名单记得定期检查变量名别配错。这三件事做到百度地图 MCP 在 CodeBuddy 里就能稳定跑下去。