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，DB0，版本 < 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，避开所有协议兼容坑：
"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里加阿里云镜像"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）。
五、排错速查表
| 报错 / 现象 | 根因 | 解决 |
|---|---|---|
| 拉包超时 | 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
