1. 从一条更新说起Redis 接入 AI 到底意味着什么前几天刷社区的时候看到一条消息说 Redis 官方开始往 AI 方向靠了支持了 MCP 协议还能跟 Claude Code 这类工具直接打通。我当时第一反应是终于来了。做后端这么多年Redis 在我手里一直是那个快得离谱的缓存和数据结构服务器键值、列表、哈希、集合、有序集合翻来覆去就这些。但这两年 AI Agent 火起来之后我明显感觉到一个断层——大模型能思考、能写代码、能调工具但它对状态这件事几乎是失忆的。每次对话结束上下文一清什么都没了。Redis 接入 AI 这件事本质上解决的就是这个断层。它让 Redis 从一个单纯的缓存中间件变成了 AI Agent 的记忆层和工具层。你可以理解为以前 Redis 是给后端程序用的现在它也能给 AI 用而且是通过 MCP 这种标准协议来用。MCP 是什么全称 Model Context Protocol你可以把它想象成 AI 世界里的USB 接口——不管你是 Claude、是本地跑的模型、还是自己写的 Agent只要双方都认这个协议就能即插即用。Redis 官方提供的 MCP Server就是把 Redis 的各种能力读写键值、操作数据结构、执行命令包装成 AI 能理解、能调用的工具。这篇文章我打算把这件事从头到尾讲透。包括 Redis 接入 AI 的整体设计思路、MCP 协议到底怎么工作、Redis MCP Server 怎么装怎么配、Claude Code 里怎么接、实际用起来有哪些坑、以及我自己踩过的几个典型问题。适合谁看后端开发、AI 应用开发者、正在折腾 Agent 和工具链的同学还有那些听说过 MCP 但一直没搞明白它到底干嘛的人。我会尽量说人话把复杂的东西拆开讲保证你看完能自己动手跑起来。2. 整体设计思路为什么是 Redis MCP 这个组合2.1 Redis 在 AI 场景里的角色转变先说清楚一件事Redis 接入 AI不是说要让 Redis 去跑大模型那是 GPU 干的活。Redis 在这里的角色是状态管理和工具执行。我把它归纳成三个层面。第一个层面是短期记忆。AI Agent 在多轮对话里需要记住上下文比如用户上一句说了什么、当前任务进行到哪一步。这些数据量不大但读写极频繁而且需要设置过期时间自动清理。Redis 的 String 和 Hash 结构天然适合干这个SET key value EX 3600一行命令就搞定比往数据库里塞快得多。第二个层面是长期记忆和向量检索。现在 RAG检索增强生成很火核心思路是把文档切成块、转成向量、存起来用户提问时先检索最相关的片段再喂给模型。Redis 从 2.0 版本开始支持向量相似度搜索可以存 embedding 向量并做 KNN 查询。这意味着你不需要额外部署一套向量数据库Redis 一个实例就能同时扛缓存和向量检索。第三个层面是工具调用。这是 MCP 带来的新玩法。AI 模型本身不能直接操作 Redis它只能说它想干什么。MCP Server 的作用就是把这层说翻译成实际的 Redis 命令。比如模型说帮我查一下用户 123 的购物车MCP Server 就把它翻译成HGETALL cart:123执行完再把结果返回给模型。整个过程模型不需要知道 Redis 的命令语法它只需要知道有个工具能查购物车。2.2 为什么选 MCP 而不是自己写插件你可能会问我直接给 AI 写个函数调用不就行了为什么要用 MCP这个问题我当初也想过。自己写当然可以但有几个问题绕不开。第一是复用性。你给 Claude 写一套工具换到别的模型上就得重写。MCP 是标准协议写一次所有支持 MCP 的客户端都能用。第二是维护成本。Redis 官方维护的 MCP Server 会跟着 Redis 版本更新命令支持、安全策略、性能优化都有人管你自己写的插件过半年可能就没人维护了。第三是生态。现在支持 MCP 的工具越来越多Claude Code、各种 IDE 插件、Agent 框架都在往这个方向靠你跟着标准走后面接新东西会省很多事。我个人的判断是MCP 现在有点像早期的 HTTP刚开始大家觉得我自己定义个协议也能用但最后标准化的那套会赢因为生态效应太强了。2.3 方案选型本地 Redis 还是云 Redis动手之前得先决定 Redis 跑在哪。我两种都试过说下感受。本地跑 Redis 适合开发和测试。用 Docker 一条命令就起来docker run -d -p 6379:6379 redis:7-alpine几秒钟的事。好处是延迟极低调试方便数据随便造。坏处是数据不持久容器一删就没了而且只能自己用。云 Redis 适合生产环境。现在主流云厂商都有 Redis 服务带持久化、备份、监控、自动扩容。好处是省心坏处是要花钱而且网络延迟比本地高一点。如果你只是自己玩或者做原型验证本地足够了。如果要给团队用或者上生产建议直接上云。我自己的做法是开发阶段本地 Docker验证没问题之后再把配置迁到云上。MCP Server 的连接配置是独立的切换成本很低。3. 核心细节解析MCP 协议与 Redis MCP Server 实操要点3.1 MCP 协议到底怎么工作MCP 的核心概念就三个Server、Client、Tool。Server 是提供能力的一方比如 Redis MCP Server 提供操作 Redis的能力。Client 是使用能力的一方比如 Claude Code。Tool 是具体的功能单元比如读取键值是一个 Tool执行命令是另一个 Tool。通信方式上MCP 支持两种传输stdio 和 SSE。stdio 就是标准输入输出Server 和 Client 跑在同一台机器上通过管道通信简单直接。SSE 是 Server-Sent Events走 HTTP 长连接适合 Server 和 Client 不在同一台机器的情况。Redis MCP Server 两种都支持本地开发用 stdio 就够了跨机器部署用 SSE。一次完整的工具调用流程是这样的Client 启动时先向 Server 请求工具列表Server 返回所有可用 Tool 的名称、描述和参数格式。模型根据用户需求决定调用哪个 Tool把参数按格式传过来。Client 把调用请求转发给 ServerServer 执行实际的 Redis 命令把结果返回。模型拿到结果后继续推理决定下一步做什么。注意MCP Server 返回给模型的是工具执行结果不是原始数据。比如你查一个 Hash返回的是格式化后的键值对不是 Redis 的 RESP 协议原始字节。这个转换过程由 Server 负责你不需要关心。3.2 Redis MCP Server 的安装与配置Redis 官方提供了 MCP Server用 Python 写的通过 pip 或 uv 安装。我推荐用 uv速度快依赖管理干净。# 安装 uv如果还没装 curl -LsSf https://astral.sh/uv/install.sh | sh # 用 uv 安装 Redis MCP Server uv pip install redis-mcp-server装完之后需要配置连接信息。Redis MCP Server 支持通过环境变量传参主要这几个环境变量说明示例值REDIS_HOSTRedis 主机地址127.0.0.1REDIS_PORTRedis 端口6379REDIS_PASSWORD密码没有就不填your_passwordREDIS_DB数据库编号0REDIS_SSL是否启用 SSLfalse如果你用 Docker 跑 Redis记得把端口映射出来-p 6379:6379。如果 Redis 设了密码启动时加--requirepass your_password。配置好之后可以先用命令行测试一下 Server 能不能正常启动REDIS_HOST127.0.0.1 REDIS_PORT6379 redis-mcp-server如果没报错说明 Server 本身没问题。接下来就是把它接到 Client 上。3.3 在 Claude Code 里接入 Redis MCPClaude Code 是 Anthropic 出的命令行编程助手支持 MCP 协议。接入 Redis MCP Server 的步骤不复杂但有几个细节容易踩坑。首先找到 Claude Code 的配置文件。不同系统位置不一样macOS 和 Linux 一般在~/.config/claude-code/config.jsonWindows 在%APPDATA%\claude-code\config.json。如果文件不存在就自己建一个。配置内容大概长这样{ mcpServers: { redis: { command: uv, args: [run, redis-mcp-server], env: { REDIS_HOST: 127.0.0.1, REDIS_PORT: 6379, REDIS_DB: 0 } } } }这里有个坑command写uv还是uvx还是完整路径取决于你的安装方式。如果 Claude Code 启动时报command not found大概率是路径问题把command改成uv的绝对路径就行。用which uv查一下。配好之后重启 Claude Code输入/mcp命令应该能看到 redis 这个 Server 的状态是 connected。如果显示 failed看下日志通常是 Redis 连不上或者环境变量没传对。提示Claude Code 的 MCP 配置支持热重载改完配置文件不用重启输入/mcp reload就行。这个我试了好几次才发现在官方文档里没写得太明显。3.4 工具列表与能力边界Redis MCP Server 暴露的工具不是无限多的它做了取舍。我实测下来主要有这几类键值操作get、set、delete、exists、expire数据结构操作hget、hset、lpush、lrange、sadd、smembers、zadd、zrange命令执行一个通用的 execute 工具可以跑任意 Redis 命令信息查询info、dbsize、keys谨慎使用这里要特别说一下keys命令。它在小数据量下没问题但生产环境数据量大了之后KEYS *会阻塞 Redis非常危险。Redis MCP Server 默认可能没限制这个但你自己用的时候一定要小心。更好的做法是用SCAN命令分批遍历。还有一个能力边界的问题MCP Server 默认只能操作单个 Redis 实例不支持集群模式下的跨槽操作。如果你的 Redis 是 Cluster 模式某些涉及多 key 的命令会报错。这个不是 MCP 的问题是 Redis Cluster 本身的限制。4. 实操过程从零搭一个带记忆的 AI 助手4.1 环境准备与 Redis 启动我拿一个实际场景来演示做一个能记住用户偏好的 AI 助手。用户告诉它我喜欢喝美式咖啡下次再问推荐个饮品它能想起来。先起 Redis。我用 Docker干净利落docker run -d --name redis-ai -p 6379:6379 redis:7-alpine redis-server --appendonly yes--appendonly yes开启 AOF 持久化这样容器重启数据不丢。虽然开发环境丢了也无所谓但养成习惯比较好。验证一下docker exec -it redis-ai redis-cli ping # 返回 PONG 就对了然后装 Redis MCP Server。我习惯用 uv 建个独立环境避免污染全局uv venv redis-mcp-env source redis-mcp-env/bin/activate uv pip install redis-mcp-server4.2 配置 Claude Code 并验证连接按 3.3 节的配置写好 config.json重启 Claude Code。输入/mcp看到 redis 状态是 connected 之后就可以测试了。先来个简单的让 Claude Code 往 Redis 里写个值。我在对话框里输入帮我在 Redis 里设置一个键 user:001:name值是 ZhangSan。Claude Code 会调用 Redis MCP Server 的 set 工具执行SET user:001:name ZhangSan。然后我让它读回来查一下 user:001:name 的值它调用 get 工具返回 ZhangSan。这一步验证了基本链路是通的。如果这里就失败了检查三个地方Redis 是否在跑、MCP Server 是否能独立启动、Claude Code 配置里的环境变量是否正确。4.3 实现记忆存储与检索逻辑基本链路通了之后来设计记忆的存储结构。我用 Hash 来存用户偏好key 设计成memory:user:{user_id}field 是偏好类型value 是具体内容。HSET memory:user:001 drink 美式咖啡 HSET memory:user:001 food 川菜 HSET memory:user:001 music 爵士在 Claude Code 里我可以直接说记住用户 001 喜欢喝美式咖啡它会自动调用 hset。下次我说用户 001 问推荐什么饮品它会先 hgetall 拿到所有偏好然后基于美式咖啡来推荐。这里有个设计决策为什么用 Hash 而不是 String因为 Hash 可以单独更新某个 field不用把整个对象读出来改完再写回去。比如用户改了饮品偏好只需要HSET memory:user:001 drink 拿铁其他偏好不受影响。String 的话就得先 GET 再解析 JSON 再改再 SET多两次网络往返。实操心得记忆的 key 一定要加过期时间。我一般设 30 天EXPIRE memory:user:001 2592000。不然数据越积越多查询越来越慢。用户如果长期不用记忆自动清理符合实际需求。4.4 向量检索的接入方式如果要做更智能的检索比如根据用户的历史对话找相似问题就需要向量。Redis 支持向量搜索但需要 Redis Stack 或者 Redis 8 以上版本。我用的是redis/redis-stack:latest镜像。docker run -d --name redis-vector -p 6379:6379 redis/redis-stack:latest创建向量索引FT.CREATE idx:memory ON HASH PREFIX 1 memory:vec: SCHEMA content TEXT embedding VECTOR HNSW 6 TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINE这里 DIM 是 1536对应 OpenAI 的 text-embedding-ada-002 模型输出维度。如果你用别的 embedding 模型维度要改。HNSW 是索引算法查询快但占内存多数据量不大用 FLAT 也行。写入向量的时候embedding 要转成二进制字节。Python 里用numpy.array(vec, dtypenp.float32).tobytes()。查询的时候用FT.SEARCH idx:memory *[KNN 5 embedding $vec AS score] PARAMS 2 vec binary DIALECT 2。这块 MCP Server 目前没有直接暴露向量操作的工具需要用 execute 工具跑原始命令。我试过能跑通但参数传递比较麻烦二进制数据在 JSON 里不好表示。如果向量检索是核心需求建议自己封装一层或者用专门的向量数据库。5. 常见问题与排查技巧实录5.1 连接类问题速查现象可能原因排查方法MCP Server 启动报 ConnectionRefusedRedis 没启动或端口不对redis-cli ping测试Claude Code 显示 MCP failed配置文件路径或格式错误检查 JSON 语法用/mcp看日志认证失败密码没传或传错检查 REDIS_PASSWORD 环境变量超时网络不通或防火墙拦截telnet host port测试连通性命令执行报 NOAUTHRedis 设了密码但没传同上确认密码5.2 性能与安全注意事项性能方面MCP 调用是有开销的。每次工具调用都要经过 Client 序列化、网络传输、Server 反序列化、执行命令、再序列化返回。单次开销大概几毫秒到几十毫秒取决于网络。如果 AI 需要频繁读写 Redis比如每轮对话都查十几次累积起来就明显了。我的做法是能批量就批量用 pipeline 或者一次拿多个 key减少往返次数。安全方面有几个点必须注意。第一MCP Server 默认能执行任意 Redis 命令包括FLUSHALL、CONFIG SET这种危险操作。生产环境一定要用 Redis 的 ACL 功能限制权限给 MCP Server 用的账号只开必要的命令。第二不要把 MCP Server 暴露到公网SSE 模式如果没有认证任何人都能连。第三敏感数据不要明文存 Redis该加密加密。# 创建受限用户 ACL SETUSER mcp_user on password ~memory:* get set hget hset hgetall -dangerous这条命令创建了一个用户只能操作memory:开头的 key只能执行 get/set/hget/hset/hgetall禁用了所有危险命令。5.3 我踩过的三个坑第一个坑环境变量没传进去。我在 config.json 里写了 env但 Claude Code 启动 MCP Server 时没读到。后来发现是command用了uv run而uv run会重新解析环境把父进程的环境变量过滤掉了。解决办法是用uv run --env-file .env或者直接在 args 里传参。第二个坑中文乱码。Redis 默认用 UTF-8但 Windows 下的 redis-cli 有时候会用 GBK导致写入的中文读出来是乱码。MCP Server 走的是二进制协议一般不会有这个问题但如果你用 redis-cli 手动验证记得加--raw参数。第三个坑大 key 导致超时。我有个测试数据不小心往一个 List 里塞了十万条MCP Server 执行LRANGE key 0 -1的时候直接卡死Claude Code 等超时了。后来改成LRANGE key 0 99只取前 100 条。教训是AI 调用的工具一定要有分页或者数量限制不能让模型随便拉全量数据。提示Redis MCP Server 的日志默认输出到 stderrClaude Code 会把它捕获。如果出问题在 Claude Code 里输入/mcp logs redis能看到详细日志。这个命令藏得比较深但排查问题时非常有用。6. 扩展玩法把 Redis 变成 Agent 的共享工作台6.1 多 Agent 协作时的状态同步单个 Agent 用 Redis 已经能解决记忆问题但多 Agent 协作的时候Redis 的价值更大。想象一个场景Agent A 负责收集信息Agent B 负责分析Agent C 负责生成报告。它们之间需要传递中间结果。用 Redis 的 List 做消息队列Agent ALPUSH task:queue {...}Agent BBRPOP task:queue 30阻塞等待。用 Hash 做共享状态所有 Agent 都能读写同一个 key。用 Pub/Sub 做事件通知一个 Agent 完成工作后PUBLISH task:done task_id其他 Agent 订阅这个频道。MCP 让每个 Agent 都能通过统一的接口操作这些数据结构不需要各自实现一套 Redis 客户端。我试过用三个 Claude Code 实例分别扮演不同角色通过 Redis 交换数据跑起来还挺顺的。6.2 与 Skill 体系的结合思路最近 Skill 这个概念很火简单说就是把一组操作封装成一个可复用的能力单元。Redis MCP Server 提供的工具是原子操作Skill 可以把它们组合成更高级的功能。比如做一个用户画像更新的 Skill先 hgetall 拿现有画像合并新信息再 hset 写回去最后 expire 刷新过期时间。这一串操作封装成一个 SkillAI 调用的时候只需要说更新用户 001 的画像不用关心底层用了哪些 Redis 命令。Skill 的粒度怎么把握我的经验是一个 Skill 对应一个完整的业务动作不要拆得太细。太细了 AI 要调很多次太粗了灵活性不够。一般 3 到 5 个 Redis 命令能完成的事情封装成一个 Skill 比较合适。6.3 后续可以探索的方向Redis 接入 AI 这件事还在早期很多玩法没被挖掘出来。我目前关注几个方向一是 Redis 的 Stream 数据结构做 Agent 的事件溯源每个决策都记一条方便回溯和调试二是用 Redis 的过期和淘汰策略做 Agent 的短期记忆管理自动遗忘不重要的信息三是把 Redis 的发布订阅和 MCP 的通知机制结合让 Agent 能被动接收事件而不是轮询。这些我都还在试有些跑通了有些还在踩坑。等有成熟经验了再单独写一篇。眼下最实在的建议是先把基础的记忆存储和工具调用跑起来用起来之后你自然会发现有更多可以优化的地方。别一上来就追求大而全的架构从一个小场景切入跑通了再扩展这是我做了这么多项目最深的体会。