CodeBuddy中配置Redis MCP 连接与排错实战

从零配置 Redis MCP Server，到踩遍所有坑最终打通，列出数据库全部 key 的完整实录。适用于 Redis < 6.0 的本地环境。

一、背景与目标

在 CodeBuddy（或其它支持 MCP 协议的客户端）中，通过Redis MCP Server让 AI 直接连接本地 Redis 数据库，执行keys、get、info等操作。

环境信息：

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

二、最终可用配置（先给结论）

直接用 Node.js 版@wenit/redis-mcp-server，避开所有协议兼容坑：

"redis-server-local":{"command":"D:/SoftWare/node22/npx.cmd","args":["-y","@wenit/redis-mcp-server"],"env":{"REDIS_HOST":"127.0.0.1","REDIS_PORT":"6379","REDIS_PASSWORD":"123456","REDIS_DB":"0"},"description":"Redis本地数据查询服务","disabled":false}

配置文件路径：C:\Users\admin\.codebuddy\mcp.json的mcpServers节点下。
改完后必须重启 MCP 连接（禁用再启用，或重启 CodeBuddy）才会生效。

三、完整操作流程

步骤 1：编辑 MCP 配置文件

打开C:\Users\admin\.codebuddy\mcp.json，在mcpServers下加入上面「最终可用配置」。

步骤 2：重启 MCP 连接

配置文件改动不会自动重启已运行的 MCP 进程，必须手动触发：

• 方法一（推荐）：CodeBuddy 设置 → MCP 服务器 →redis-server-local→ 先「禁用」再「启用」。
• 方法二：完全退出并重启 CodeBuddy。

步骤 3：验证连接

在对话里直接说「列出所有 key」，AI 会调用 MCP 工具。Node.js 版提供的常用工具：

步骤 4：成功结果示例

Redis 全部 Key（DB 0，共 3 个）： 1. graph:thread:meta:test-002 2. graph:thread:reverse:0310020b-b8e4-401e-9af7-6d21823057d9 3. graph:checkpoint:content:0310020b-b8e4-401e-9af7-6d21823057d9

四、踩坑全记录与解决方案

按实际发生顺序排列，每个坑都是「换配置 → 重启 → 再试」的循环。

坑 1：pypi.org下载超时

• 现象：用 Python 版uvx安装redis-mcp-server时拉包超时。

• 原因：默认走 pypi 官方源，国内网络不稳。

• 解决：在env里加阿里云镜像

  "UV_INDEX_URL":"https://mirrors.aliyun.com/pypi/simple"

坑 2：pip install找不到包 / Python 版本过低

• 原因：本机 Python 版本太低，不满足 MCP 包要求。
• 解决：改用uvx（自带独立环境）而非系统pip。

坑 3（核心）：unknown command 'HELLO'

• 现象：所有命令（dbsize、scan_all_keys）报unknown command 'HELLO'。
• 原因：HELLO是Redis 6.0 引入的 RESP3 协议握手命令。Python 官方版redis-mcp-server底层redis-py默认发 RESP3 握手，而本地 Redis < 6.0 不认识，直接拒绝。这是已知 Bug（redis/mcp-redis Issue #149）。
• 无效尝试：在 URL 加?protocol=2强制 RESP2 —— Python 版不识别这个参数，无效。
• 最终解决：换成 Node.js 版@wenit/redis-mcp-server（底层ioredis，默认 RESP2，不发HELLO）。

附带修正：如果坚持用 URL 形式，密码前要有冒号redis://:123456@host:port/0（否则123456被当成用户名）。但根治办法还是换 Node.js 版。

坑 4：zod缓存损坏ENOENT ... ur.js

• 现象：

  Error: ENOENT: no such file or directory, open 'C:\Users\admin\AppData\Local\npm-cache\_npx\...\node_modules\zod\v4\locales\ur.js' MCP error -32000: Connection closed

• 原因：npx缓存里的zod依赖包下载不完整，缺文件。

• 解决：清掉损坏的 npx 缓存让其重新下载

  Remove-Item-Recurse-Force"C:\Users\admin\AppData\Local\npm-cache\_npx\77cd0660cb120fdc"

  若仍报错，彻底清理：

  npm cache clean--forceRemove-Item-Recurse-Force"C:\Users\admin\AppData\Local\npm-cache\_npx"

  然后回 CodeBuddy 禁用再启用redis-server-local。

坑 5：改了配置但仍报旧错

• 现象：明明改了mcp.json，还是报之前的HELLO错。
• 原因：旧 MCP 进程仍在后台运行，改文件不自动重启。
• 解决：必须手动「禁用 → 启用」或重启 CodeBuddy。判断新连接是否生效：看该 MCP 的「已发现工具」是否正常加载、工具名是否变化（Python 版有scan_all_keys，Node.js 版有keys）。

五、排错速查表

六、关键经验总结

1. Redis 版本 < 6.0，直接用 Node.js 版 MCP（@wenit/redis-mcp-server），别碰 Python 官方版，能省掉HELLO协议坑。
2. 改完mcp.json一定要重启 MCP 连接，配置不会热更新。
3. npx首次运行会拉依赖，网络差 / 缓存损坏时清_npx缓存再来。
4. 用工具名判断当前跑的是哪个版本：scan_all_keys= Python 版，keys= Node 版。
5. 密码型 URL 格式：redis://:密码@host:port/db，密码前的冒号不能少。

附：验证成功后可做的操作

- 列出所有 key：keys {"pattern": "*"} - 按前缀筛选：keys {"pattern": "graph:*"} - 查看某 key 内容：get / hgetall 等对应工具 - 连通性测试：ping