Redis MCP Server

@yawlabs/redis-mcp

一键将其添加到本地 Yaw MCP 配置，让它在每个 Yaw Terminal 会话中都可用。也可以在下方手动安装。

然后为它提供 REDIS_URL。 按钮不会携带连接字符串，Yaw MCP 也不会提示输入：它只会询问名称看起来像凭据的变量，而 REDIS_URL 不符合这一条件。在设置之前，服务会在启动时因 REDIS_URL is not set 而退出。只需一步即可将其存储在 Yaw MCP 的加密保险库中：

yaw-mcp set redis env.REDIS_URL --secret

该值通过无回显提示（或管道传入的 stdin）读取，绝不会从命令行读取；保险库条目名为 redis_redis_url，服务对应的条目为 "REDIS_URL": "${secret:redis_redis_url}"。Yaw MCP 会在启动服务时读取保险库，因此更改值后，请运行 mcp_connect_deactivate redis（或启动新会话）以使新值生效。

在 Claude Code、Cursor 和任何 MCP 客户端中探索并诊断 Redis 实例。 默认只读——通过一个环境变量即可启用写入——而且枚举键时始终使用 SCAN，绝不使用 O(N) 的 KEYS，因此可以安全地连接到拥有数百万个键的生产实例。

由 Yaw Labs 构建并维护。

为什么选择它？

• 始终使用 SCAN，绝不使用 KEYS。 所有键枚举路径都使用基于游标的 SCAN，并设置有界的 COUNT 和迭代次数上限。KEYS * 会遍历整个键空间，复杂度为 O(N)，并会在整个扫描期间阻塞 Redis 的单线程事件循环——在大型实例上这无异于自找停机。SCAN 会在批次之间让出执行权。请参阅安全性。
• 只读优先的命令门控。 默认情况下，工具仅运行经过筛选的只读命令允许列表。变更命令（SET、DEL、EXPIRE、HSET 等）需要设置 ALLOW_WRITES=1。即使启用了写入，也不会开放任意执行命令（EVAL、FUNCTION、SCRIPT、MULTI、MONITOR、SHUTDOWN、CLUSTER 等）——门控使用的是经过筛选的允许列表，而不是“启用写入后允许执行任何命令”。
• 按类型读取，不会造成意外。 redis_get 会按值类型（string / hash / list / set / zset / stream）分派读取操作，并限制集合读取范围，因此百万元素的列表也不会撑爆模型上下文。redis_key_info 会读取类型 / TTL / 编码 / 内存占用，而无需拉取值本身。
• 一次调用即可检查运行状况。 redis_health 汇总 INFO + DBSIZE + 最近的 SLOWLOG，提供内存压力、驱逐策略、命中率、每秒操作数、持久化状态、复制角色、各数据库的键数量（以及其中没有 TTL 的数量），并列出最近执行缓慢的命令。
• 真正的顾问工具。 redis_advisor 是一项用于检查“我应该关注什么？”的扫描：发现大键、缺少 TTL 的键、驱逐压力（包括危险的 noeviction + 无 TTL 组合）以及分叉延迟风险——每项都标有严重程度并提供可执行的修复建议。键通过 SCAN 抽样，因此在大型实例上也很安全。
• 即时启动。 以单个打包文件形式发布，运行时零依赖。每次 npx 冷启动都无需耗时数分钟安装 node_modules。

适用范围

此服务是一个以读取为先的探索和诊断工具，而不是通用的 Redis 管理控制台。它刻意不提供 EVAL/FUNCTION/SCRIPT、发布/订阅、MONITOR、集群管理或复制控制功能。需要这些功能时，请直接使用 redis-cli。本工具旨在安全地覆盖常见的 90% 需求：“这个实例里有什么、运行状况如何、有哪些问题需要担心？”——也就是 Agent 应该能够在不造成风险的情况下针对生产环境 Redis 回答的问题。

适用于 Redis 6+ 和 Valkey。有几个 redis_health 字段（latest_fork_usec、aof_enabled）取决于运行中的服务是否在 INFO 中提供这些字段；缺失的字段会显示为 null，而不会导致报错。

快速开始

1. 在项目根目录中创建 .mcp.json

macOS / Linux / WSL：

{
  "mcpServers": {
    "redis": {
      "command": "npx",
      "args": ["-y", "@yawlabs/redis-mcp@latest"],
      "env": {
        "REDIS_URL": "redis://:password@host:6379/0"
      }
    }
  }
}

Windows：

{
  "mcpServers": {
    "redis": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/redis-mcp@latest"],
      "env": {
        "REDIS_URL": "redis://:password@host:6379/0"
      }
    }
  }
}

为什么 Windows 上需要额外步骤？ 从 Node 20 开始，child_process.spawn 无法直接执行 .cmd 文件（Windows 上的 npx 就是这种文件）。使用 cmd /c 包装是常见的解决方法。

2. 重启并批准

重启 Claude Code（或你的 MCP 客户端），并在提示时批准 redis MCP 服务。

3. （可选）启用写入

默认情况下为只读。如需让 Agent 通过 redis_command 运行会修改数据的命令（SET、DEL、EXPIRE、HSET 等），请添加 ALLOW_WRITES=1：

"env": {
  "REDIS_URL": "redis://...",
  "ALLOW_WRITES": "1"
}

建议仅对开发/测试实例启用此设置。即使启用了写入，任意代码执行命令仍会被屏蔽。

安全性

使用 SCAN，而不是 KEYS——这是至关重要的选择。 Redis 是单线程的。KEYS pattern 会以一个不可中断的操作遍历整个键空间；在拥有数百万个键的实例上，这会在操作期间阻塞所有其他客户端，效果相当于你自己触发了一次拒绝服务攻击。此服务中所有枚举键的路径（redis_scan、顾问工具的键采样、redis_get 的集合读取）都使用基于游标的 SCAN/SSCAN，并设置有界的 COUNT 和严格的迭代上限，在批次之间让出事件循环。命令门会明确拒绝 KEYS，并提示改用 redis_scan。

默认只读。 未设置 ALLOW_WRITES=1 时，仅允许运行只读允许列表中的命令；其他所有命令都会在到达 Redis 之前被拒绝。设置 ALLOW_WRITES=1 后，还会额外允许一组经过筛选的修改类命令，但任意代码执行命令（EVAL、FUNCTION、SCRIPT、MULTI/EXEC、MONITOR、SHUTDOWN、REPLICAOF、CLUSTER、MIGRATE 等）在所有模式下仍会被屏蔽。命令门采用默认拒绝策略：不在任一允许列表中的命令都会被拒绝，因此我们未预料到的命令也无法漏过。

将 Redis ACL 用作主要控制措施。 与数据库角色类似，最稳妥的做法是在 REDIS_URL 中使用权限最小化的 Redis 用户（ACL SETUSER mcp on >pass ~* +@read）。这样 Redis 会在服务端执行访问边界，而不依赖此服务的命令门。ALLOW_WRITES 则在此基础上提供纵深防御。

如需报告漏洞，请参阅 SECURITY.md。

工具

工具	说明
redis_scan	使用基于游标的 SCAN 枚举键（绝不使用 KEYS）。可选的 glob match、值的 type 筛选器和可恢复的 cursor。数量上限为 REDIS_MAX_KEYS。
redis_key_info	检查单个键而不读取其值：类型、TTL（秒/毫秒）、编码、内存占用、空闲时间。用于探测大键 / 缺少 TTL 的键。
redis_get	读取键的值，并按类型分派（字符串 / 哈希 / 列表 / 集合 / 有序集合 / 流）。集合读取通过 limit 分页。始终为只读。
redis_command	通过安全门运行单条 Redis 命令。读取命令始终可以运行；写入命令需要 ALLOW_WRITES=1；KEYS 和任意执行命令会被拦截。用于运行没有专用工具的命令。
redis_health	一次调用即可通过 INFO + DBSIZE + SLOWLOG 获取健康状况快照：内存压力、淘汰策略、命中率、每秒操作数、持久化、复制角色、每个数据库的键数以及近期慢命令。
redis_slowlog	Redis 慢日志中的近期条目——命令、微秒数、时间戳、客户端。只读（SLOWLOG GET）。
redis_advisor	一次调用汇总健康检查结果：大键、缺少 TTL 的键、淘汰压力、fork 延迟风险。每条发现都包含严重程度和修复建议。通过 SCAN 抽样，在大型实例上也安全。

配置

所有环境变量都从 MCP 服务的环境中读取。最后三个环境变量由 redis-mcp 启动器读取，而非服务读取，因此当主机直接运行 dist/index.js 时，它们不会生效；启动器的 oam 版本检查也不会生效（参见 运行时）：

变量	默认值	用途
REDIS_URL	（必填）	Redis 连接字符串，例如 redis://:pass@host:6379/0；使用 TLS 时可用 rediss://...。
ALLOW_WRITES	未设置	设为 1 或 true，以允许通过 redis_command 执行经过筛选的变更命令。无论如何都会屏蔽可任意执行代码的命令。
REDIS_COMMAND_TIMEOUT_MS	10000	单条命令的超时时间。运行时间更长的命令会被中止，避免卡住的调用让 Agent 一直等待。
REDIS_CONNECT_TIMEOUT_MS	10000	TCP 连接超时时间。若不设置，连接失效的主机会一直挂起，直到操作系统放弃（约 2 分钟）。
REDIS_MAX_KEYS	1000	单次扫描返回的键数量上限，以及 redis_get 返回的集合元素数量上限。上限为 1000000；小数向下取整；小于 1 或非数值时使用默认值。
REDIS_MAX_VALUE_BYTES	262144	redis_get 返回的字符串值的字节数上限（256 KiB）。超过上限的字符串将返回前 REDIS_MAX_VALUE_BYTES 个字节，并附带 truncated: true 和完整的 length。上限为 64000000（64 MB）；小数向下取整；小于 1 或非数值时使用默认值。宿主可能会将整个工具结果限制在更小的大小——Yaw MCP 默认保留前 100,000 个字节（YAW_MCP_MAX_RESULT_BYTES）——因此 redis_get 会把 length 和 truncated（以及集合大小）放在值之前：结果被截断时只会丢失有效载荷，不会丢失说明值已被截断的字段。
REDIS_SCAN_COUNT	100	每次 SCAN 迭代的 COUNT 提示值。值越大，往返次数越少，但每次迭代的工作量越大。上限为 1000000；小数向下取整；小于 1 或非数值时使用默认值。
REDIS_TLS_REJECT_UNAUTHORIZED	未设置	设为 false 可跳过 TLS 证书验证，即证书链和主机名检查。连接仍会加密，但不再进行身份验证。这是私有 CA 场景下的最后手段：优先使用 NODE_EXTRA_CA_CERTS，参见连接托管的 Redis。
REDIS_MCP_RUNTIME	auto	执行服务的 JS 运行时：auto（优先使用可找到的最新 oam，版本不低于 0.18.0；否则使用 Node）、oam（同上，但若无法使用则报错退出，而不是回退）、node（始终使用 Node——在 npx 下进程内运行；客户端通过 oam run 启动命令时，则交由 PATH 中的 Node 执行）。不区分大小写；其他任何值——例如拼写错误的 nodejs，或带有首尾空格的值——都会在不发出警告的情况下按 auto 处理。参见运行时。
OAM_BIN	未设置	指定优先于自动发现使用的 oam 二进制文件路径，版本需为 0.18.0 或更高。如果文件不存在、版本过旧或无法运行，启动器会向 stderr 输出说明，然后继续自动发现。在 REDIS_MCP_RUNTIME=node 时会忽略此变量；如果启动器已在 oam 0.18.0 或更高版本下运行，也会忽略此变量，除非设置了 REDIS_MCP_SANDBOX=1。
REDIS_MCP_SANDBOX	未设置	值恰为 1 时，会在 oam 的 --permission 沙箱中运行服务：禁止文件系统访问和子进程，将网络访问限制为 REDIS_URL 中的主机和端口（URL 未指定端口时为 6379）。IPv6 字面地址（redis://[::1]:6379）也会像其他主机一样受到限制。主机和端口的读取方式与 ioredis 相同，因此无协议的 REDIS_URL（127.0.0.1:6379）、纯端口号、查询字符串中的 host 或 port，以及没有主机的 URL（localhost）也会受到限制。绝对 Unix 套接字路径（/run/redis.sock、无协议的 host/path，或查询字符串中的 path）会被限制为该确切路径，并授予对该路径的文件系统读写权限，这是 oam 0.18.0 在 --permission 下连接套接字所需的权限；无法授予相对套接字路径的权限，启动器会说明沙箱将拒绝该路径。（oam 0.18.0 是首个支持连接 Unix 套接字的 oam；其更新日志指出，Unix 相关功能尚未在 Windows 以外的平台上进行测试，本权限授予也同样如此。）如果 REDIS_URL 未指定可通过权限规则表示的单一端点——例如 URL 无法解析、主机为空、主机包含逗号，或端口不在 1-65535 范围内——网络权限将不受限制，启动器会向 stderr 说明。REDIS_MCP_SANDBOX 的值不是 1 时会在不发出警告的情况下忽略。只有实际启动新的 oam 进程时，此变量才会生效。任何在未启用沙箱的情况下运行服务的回退操作都会向 stderr 输出说明，但宿主可能不会显示 stderr，因此请同时设置 REDIS_MCP_RUNTIME=oam，以便在无法使用时退出，而不是回退。启动器只会启动 oam 0.18.0 或更高版本，该版本包含沙箱所依赖的全部修复：根据 oam 的更新日志，直到 0.9.1，--permission 才涵盖全部 fs 和 child_process；直到 0.15.0，端口权限才变得精确。

连接托管的 Redis（Upstash、ElastiCache、Redis Cloud 等）

使用 rediss:// URL 启用 TLS。在 Node 和 oam 上都适用，包括 sandbox。

如果服务提供商提供的证书由运行时信任库不识别的私有 CA 签名（stderr 上的症状为：self-signed certificate in certificate chain、unable to verify the first certificate 或 self-signed certificate；在 Node 和 oam 上表现相同），最佳解决方法是信任该 CA：将 NODE_EXTRA_CA_CERTS 指向其 PEM 文件。Node 和 oam 0.15.3+ 都会读取此变量，且连接仍会经过完整验证：

"env": {
  "REDIS_URL": "rediss://default:pass@host:6379",
  "NODE_EXTRA_CA_CERTS": "/path/to/provider-ca.pem"
}

如果无法获取 CA 证书，则改为添加 REDIS_TLS_REJECT_UNAUTHORIZED=false：

"env": {
  "REDIS_URL": "rediss://default:pass@host:6379",
  "REDIS_TLS_REJECT_UNAUTHORIZED": "false"
}

这会完全关闭证书验证，包括证书链和主机名检查，因此连接仍会端到端地通过 TLS 加密，但不再经过身份验证。请尽可能优先使用 NODE_EXTRA_CA_CERTS。

运行时

已发布的 redis-mcp 命令是一个小型启动器，它会优先使用能找到的最新 oam JavaScript 运行时，并在找不到时回退到 Node。它只使用最新的 oam 版本，目前为 0.18.0，绝不会在更旧的版本上运行服务。**如果你没有 oam，则一切照旧：**回退会自动进行，而且由于 npm 已启动 Node 来运行启动器，因此服务器会通过进程内 import() 加载，不会额外启动子进程。

**为什么是 0.18.0。**这是最新的 oam 版本，也是此服务经过验证的版本；随着 oam 发布新版本，启动器会提高最低版本要求，因此即使较旧的 oam 能正常运行，也会被跳过。最低版本要求最早在 0.15.3 时开始生效。在该版本之前，oam 的 TLS socket 缺少 ioredis 所调用的部分 net.Socket 方法，并且在服务器断开连接时不会自行关闭，因此 rediss:// 会在首次工具调用时导致服务器崩溃（YawLabs/oam#132），而且 oam 会忽略 NODE_EXTRA_CA_CERTS（YawLabs/oam#136）。0.15.3 修复了这两个问题，因此从该版本起，TLS 的行为与 Node 相同。如果只能找到低于 0.18.0 的 oam，启动器会改用 Node 运行服务器——通过 npx 启动时在独立进程中运行；由主机通过旧版 oam run 启动时，则交由 PATH 中的 Node 运行——并提示运行 oam self-update（这是 oam 自带的、经过签名验证的更新程序；从低于 0.18.0 的 oam 运行时，它会运行新的安装程序，而验证发行版需要 ssh-keygen 8.1 或更高版本）。只有完全找不到 oam 时，它才会引导用户访问 oamjs.org。如果使用旧版 oam run 的主机在 PATH 中找不到 Node，或者设置了 REDIS_MCP_RUNTIME=oam，它就会退出。捆绑自带 oam 的主机需要更新主机本身。若主机直接在 oam 下运行 dist/index.js，则会跳过上述所有步骤；在低于 0.15.3 的 oam 上运行时，服务器会在每次 rediss:// 工具调用时返回一条指出应更新到哪个版本的错误，而不是崩溃。

运行时的选择方式：

• 已经运行在 oam 上。 如果启动器本身运行在 oam 0.18.0+ 下（即在 bin 上运行 oam run 的宿主），服务会导入该进程：不会进行发现或生成进程，OAM_BIN 会被忽略，并满足 REDIS_MCP_RUNTIME=oam。REDIS_MCP_SANDBOX=1 会跳过此步骤，因为只有新生成的 oam 才能应用 --permission：启动器会在沙箱中重新启动当前运行于其上的 oam，即使该 oam 不在任何安装位置且不在 PATH 中（可用的 OAM_BIN 仍优先）。
• 否则，进行发现。 如果 OAM_BIN 的版本为 0.18.0 或更高，启动器会使用它。否则，启动器会询问所有能找到的 oam——OAM_INSTALL_DIR（若已设置）、默认安装位置（Windows 上依次为 %LOCALAPPDATA%\oam\bin 和 ~/.oam/bin，其他平台为 ~/.oam/bin），然后是 PATH——获取其版本，并生成版本为 0.18.0 或更高的最新版本；如果版本相同，则优先选择已安装的副本。在 Windows 上，只有 oam.exe 才会被计入。若 OAM_BIN 不存在、版本较旧或无法运行，启动器会在 stderr 中指出它，然后继续发现。
• 没有可用的 oam。 在 auto 模式下，服务会改为在启动器自己的进程中运行（旧版 oam 宿主会进行移交，见下文）。如果启动器跳过了 OAM_BIN、发现的 oam 版本过旧或无法运行、（在 Windows 上）PATH 中存在 oam.cmd / oam.bat、所选 oam 启动失败，或设置了 REDIS_MCP_SANDBOX=1，启动器会在 stderr 中说明。若提示跳过的是可运行但版本过旧的 oam，则会建议更新它。如果完全没有找到 oam，且未要求启用沙箱，启动器会静默回退；从旧版 oam 宿主移交时始终会给出提示，该提示会在启动器确定是否找到 Node 后写入一次。oam 启动后，运行服务期间发生的故障属于启动失败，不会触发回退。
• 旧版 oam 宿主绝不会提供服务。 如果启动器运行在低于 0.18.0 的 oam 下，它会将服务移交给最新的可用 oam；若没有可用的 oam，则移交给 PATH 上的 Node；两者都不存在时会报错退出。
• 覆盖选项。 REDIS_MCP_RUNTIME=oam 会将所有回退都变成启动失败。REDIS_MCP_RUNTIME=node 会跳过发现并始终运行 Node：在 Node 下于启动器自己的进程中运行；在 oam 下则移交给 PATH 上的 Node。

启动器从 oam 宿主启动的子进程，其 NODE_OPTIONS 中会移除继承的任何 --permission / --allow-*：oam 0.18.0 会将自己的权限标志追加到每个子进程的 NODE_OPTIONS 中，而此启动器应用的沙箱会通过所生成 oam 的命令行传递，绝不会通过环境传递。

任何回退都不会携带 --permission——无论是在同一进程中运行，还是移交给 Node——因此，在 auto 模式下设置 REDIS_MCP_SANDBOX=1 时，服务最终可能会处于无沙箱状态。每次此类回退都会在 stderr 中说明这一点（without --permission），但宿主可能不会显示 stderr。如果不能接受服务处于无沙箱状态，请同时设置 REDIS_MCP_RUNTIME=oam。

故障排除

REDIS_URL is not set — MCP 客户端启动服务时没有传入环境变量。尤其是在 Windows 上，通过 bash / PowerShell 配置文件设置的环境变量不会传递给通过 cmd 启动的 MCP 服务。请将 REDIS_URL 直接放入 .mcp.json 的 env 块中。在 Yaw MCP 下，使用 yaw-mcp set redis env.REDIS_URL --secret 设置（参见本页顶部）。

NOAUTH Authentication required — 此实例需要密码，但 URL 中没有密码。请添加密码：redis://:yourpassword@host:6379（注意前面的冒号——默认用户的用户名为空）。

<COMMAND> mutates state and is blocked: ALLOW_WRITES is not set — 你在只读模式下通过 redis_command 发起了写入操作。请在 env 块中添加 ALLOW_WRITES=1（用于开发／测试），或者——更简洁的做法——使用权限范围符合你所需访问权限的 Redis ACL 用户。

KEYS is blocked — 这是有意为之。请使用 redis_scan（基于游标）枚举键；在大型键空间中，它比 KEYS 更安全。

第一条命令较慢，后续命令很快 — 这是预期行为。客户端会在执行第一条命令时才建立连接；之后的命令会复用该连接。

开发

npm install
npm test          # build + unit tests (no live Redis needed)
npm run check:compliance   # @yawlabs/mcp-compliance, on Node and on oam, against a local RESP stub
npm run check:oam-floor    # OAM_MIN agrees with the docs and tests, and is the latest oam release

单元测试套件涵盖纯逻辑——命令允许列表强制检查、SCAN 游标分页、INFO/SLOWLOG 解析和顾问启发式逻辑——无需 Redis 实例即可运行。需要测试实时路径的集成测试（npm run test:integration）需要一个可随时销毁的 Redis 实例，并通过 REDIS_URL 指定。

许可证

MIT © 2026 YawLabs