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

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

一、背景与目标

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

环境信息：

项目	值
操作系统	Windows（PowerShell）
Redis	本地 `127.0.0.1:6379`，密码 `123456`，DB `0`，版本 < 6.0
Node.js	v22（`D:/SoftWare/node22/`）
配置文件	`C:\Users\admin\.codebuddy\mcp.json`

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

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

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

json 复制代码

"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 版提供的常用工具：

工具	作用
`keys`	按 pattern 列出 key（`{"pattern": "*"}`）
`get` / `set`	读写字符串
`info`	服务器信息
`ping`	连通性测试

步骤 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 里加阿里云镜像

json 复制代码

"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 缓存让其重新下载

powershell 复制代码

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

若仍报错，彻底清理：

powershell 复制代码

npm cache clean --force
Remove-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）。

五、排错速查表

报错 / 现象	根因	解决
拉包超时	pypi 源慢	加 `UV_INDEX_URL` 镜像
`pip` 找不到包	Python 版本低	改用 `uvx`
`unknown command 'HELLO'`	官方 Python 版发 RESP3，Redis<6.0 不支持	换 `@wenit/redis-mcp-server`（Node 版）
`ENOENT ... zod/.../ur.js`	npx 缓存损坏	删 `_npx` 缓存重下
改配置无效、仍报旧错	旧进程没重启	禁用再启用 / 重启客户端
`Connection closed -32000`	MCP 进程启动即崩溃	看具体报错，多为依赖缺失或配置错

六、关键经验总结

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

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

复制代码

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

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