企业官网建设流程全解析

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 Key（AK）

打开百度地图开放平台控制台，注册或登录后创建一个应用。这里有个关键点：应用类型必须选「服务端」，不要选浏览器端或 iOS/Android 端，因为 MCP Server 是在服务端发请求的。

创建完成后你会拿到一个 AK（API Key）。拿到之后还有一步容易漏：在应用里启用「MCP (SSE)」服务。如果不启用，调用可能直接失败或者性能很差。这一步在控制台的服务勾选里能找到。

AK 是敏感凭证，明文写在 mcp.json 里，所以千万别把它提交到 git 仓库。建议本地用 .gitignore 把 .codebuddy 目录排除掉，或者用环境变量注入的方式管理。

2.2 TaoToken 统一 Key/API 通道的接入位置

如果你同时在用多个模型或工具，管理一堆 Key 会很烦。TaoToken 提供了一条统一的 API 通道，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。

在 CodeBuddy 里接入百度地图 MCP 的场景下，TaoToken 的作用是帮你统一管理模型侧的 Key。也就是说，百度地图的 AK 归百度地图管，模型调用的 Key 归 TaoToken 管，两者不冲突。你可以在 TaoToken 的 API Keys 页面（https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ）生成一个 Key，然后在 CodeBuddy 的模型配置里填上。

具体来说，CodeBuddy 的模型配置里需要填三件套：Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api ，API Key 填你在 TaoToken 生成的 Key，Model ID 按你实际用的模型填。这样模型对话走 TaoToken 通道，百度地图 MCP 走百度地图 AK，各管各的，互不影响。

如果你还没决定用哪个模型，可以先到模型对话页面（https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ）试一下，确认通道通了再往下配。

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.json，macOS/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.cmd，macOS/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 版用 BAIDU_MAP_API_KEY，Python 版才用 BAIDU_MAPS_API_KEY。配错的话鉴权会直接失败，而且报错信息不一定明确指向变量名，排查起来很费时间。建议直接用 Node 版，生态更成熟，npx 拉起也方便。

3.4 生效方式

写完 mcp.json 后，配置不会自动生效。你需要在 CodeBuddy 里对这个 MCP 做一次「禁用 → 启用」操作，或者直接重启 CodeBuddy。实测下来，禁用再启用比重启快，推荐用这个方式。

3.5 工具清单速查

配置生效后，这个 MCP 会暴露 10 个工具：

经典三件套 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 家，按由近及远）：

距离是直线估算，实际步行或驾车距离会更长。坐标来自百度 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_KEY，Python 版才是 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 生成的 Key，Model 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 Plan（https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ），把模型调用和工具链统一管理起来。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，API Keys 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。

最后提醒一句：AK 别提交到 git，IP 白名单记得定期检查，变量名别配错。这三件事做到，百度地图 MCP 在 CodeBuddy 里就能稳定跑下去。