redis-guard-mcp

一个 Redis MCP 服务器，其“只读”不是标签——它就是完整的工具面。每个工具都通过 redis-py 的类型化 API 精确映射到一条安全、只读的 Redis 命令。这里不存在可以被误标为“运行这条命令字符串”的工具。

为什么存在这个项目

Redis 是专业后端中部署最广的基础设施之一（缓存、会话存储、队列、限流器、发布/订阅），而它的命令面包含了一些在广泛使用的数据存储中最为危险的单条命令：

• EVAL/EVALSHA/FCALL — 在 Redis 进程内执行任意 Lua 脚本。

• CONFIG SET dir + CONFIG SET dbfilename + SAVE — 单独通过 Redis 即可把任意文件写入磁盘的标准且被广泛采用的技巧（例如把 web shell 写入 web 根目录，或写入 cron 任务）。

• MODULE LOAD — 将任意共享库动态载入 Redis 进程。如果攻击者能把 .so/.dll 放到磁盘上，这就是直接的 RCE。

• FLUSHALL/FLUSHDB — 立刻删除数据库中的所有键，不要求确认。

• SHUTDOWN、DEBUG、SLAVEOF/REPLICAOF、ACL、CLIENT KILL — 可令服务器崩溃、劫持复制、改写权限、终止回话的管理命令面。

一份公开的 MCP 服务器审核发现，某个命令执行工具在其元数据中标注了 readly true，但实际仍然会接受并执行 EVAL 和 FLUSHALL——这个元数据仅为装饰性，并没有真正实施强制。直接对照官方 redis/mcp-redis 服务器验证：其正是因为文档说明，针对以上任意外连中，唯一的威胁只能由你自己去一步步配置 Redis ACL——该服务器自带了内置的 EVAL、FLUSHALL、CONFIG、MODULE 或 DEBUG 拦截，也没有自己的只读模式。安全性完全由运维人员负责，这是其默认和开箱即用的状态。

redis-guard-mcp 的不同之处

1. 允许列表不仅是过滤器, 它就是工具表面。 此服务器里没有任何一个入口接受任意命令字符串。每个工具都是一个具体的 Python 函数，它调用一个特定 redis-py 方法（r.get(key)、r.hget(key, field)……）。因此，EVAL、CONFIG、MODULE、FLUSHALL 或任何其他未显式实现为独立工具的命令，根本没有富国传输的可能码路径——这不是在运行时被拒绝或被拒绝的原因，而是因为发送它的客户端代码在此处根本不存在。

2. 也真正拥有权限强制，而不仅仅是应用层限制。 推荐配置（以及启动时检查的配置）使用一个以 @read -@write -@admin -@dangerous 创建的 Redis ACL 用户连接。即便此服务器自身代码存在 bug，也无法对正确使用配置的连接执行任何写或如下管理命令，因为 Redis 本身会在协议层拒绝它们。规则的顺序问题 —— CLIENT KILL/PAUSE/LIST/UNBLOCK 同时属于 @admin 和 @connection 两类，因此 ... -@admin +@connection（错误的顺序）会 silently 重新授权这四条命令。这不是空想：早期版本的配置脚本中正是这个顺序；安全审查对一个附带到这个“正确配置”的用户执行了 CLIENT PAUSE，并且能够成功——用户某人借此获得了全服务器的拒绝服务能力，而本项目的文档曾正确描述了该用户提供的此类能力。修复就是先放 +@connection；正确的顺序及为何不能换位的说明见 scripts/setup__redis.sh。

3. 所有集合的操作全部基于游标，绝不一次性全部取出。 KEYS 出现在 Redis 自带的 @dangerous 类别中，因为一次调用就可以原序列化大键空间而阻塞整个服务器——HGETALL 作用于大哈希和 SMEMBERS 作用于大集合时类似，只是不为人知而已。此处每一个“把集合给我”的工具要么基于游标（redis_scan_keys/redis_hscan/redis_sscan），要么只能每次取出暂时最多 1000 项并显式返回一个 truncated 标志——绝不会出现一次调用就让服务器独立地将无大小的集合物化出来的情况。

4. 做到了真正询问 Redis 而非自己重新实现 Redis 语义的权限检查。 redis_check_permissions() 用 ACL DRYRUN——Redis 判断“该用户下，这条命令真能成功吗？”——用来检查一份精选出来的危险命令的列表，而不是尝试通过解析 ACL 规则来重新推导答案（这正是上文规则顺序问题产生的机制：按类别列表单独不再能看出 @admin 与 @connection 重叠说明不了问题）。would_succeed 应当始终为空。

工具

设置

pip install redis-guard-mcp
export REDIS_GUARD_URL="redis://readonly_user:password@localhost:6379/0"
redis-guard-mcp

REDIS_GUARD_URL 是必需的——没有默认值。在 MCP 客户端的环境配置中设置它并把它指向 redis-guard-mcp 命令。可参考 scripts/setup_dev_redis.sh 中的示例，该示例以正确的排列顺序配置受限 ACL 用户（+@connection +@read -@write -@admin -@dangerous，外加 redis_check_permissions 本身所需的一个精细的 ACL WHOAMI/ACL GETUSER/ACL DRYRUN 例外——为什么这三个命令不在 @re ad 范围内却可以安全地授予，请参见 client.py）。

测试

pip install -e ".[dev]"
scripts/setup_dev_redis.sh   # starts a Redis container + provisions the ACL user + seeds data
pytest tests/ -v

34 个测试，几乎全部针对真实本地容器（少量纯配置校验测试不需要 Redis，且基础上会判断并自动跳过），如果无法到达 docker 容器的则会自动跳过。还包括一个针对上述 CLIENT PAUSE 顺序这条具体 bug 的回归测试，以及一个基于 AST 的结构化测试，用于断言 commands.py 调用的具体 redis-py 方法集合，这样未来有新增工具时会在该处被注意到，而不会悄悄通过代码审查。

状态

v0.1.0。在第一次提交之前已执行了一次对抗性安全审查，它发现并已修复了：上面的 ACL 规则顺序 bug（确实通过自行运行 CLIENT PAUSE 验证过），最初按类别检查权限带来的两个盲点（现引入了 ACL DRYRUN 替换），对普通 Redis 实例上无界集合读取的问题现在已改为封顶 / 分页，使非幂等的开发用数据 seed 以及 MCP 工具层中的 lazy singleton 线程安全竞态已解决。

许可证

MIT