redis-mcp-server

基于 Node.js + TypeScript 的安全 Redis MCP Server，让 Claude Desktop、Cursor、Codex、VS Code 等 MCP Host 可以通过标准化工具安全访问 Redis。

语言 / Languages： 中文 · English (US) · Français · Русский · 한국어

功能

• Redis 连接管理与自动重连

• String / Hash / List / Set / Sorted Set / Stream 数据结构操作

• Key 扫描、过期、TTL 管理

• Pub/Sub 发布（可配置）

• 批量操作（Pipeline / MULTI-EXEC）

• MCP Resources（状态、Key 读取）

• Key 命名空间前缀隔离

• 只读模式、删除/发布权限控制

• 返回数量与数据大小限制

• stdio 传输，兼容主流 MCP Host

Related MCP server: mcp-libsql

安全设计

• 禁止任意命令执行：不提供 redis_raw_command 等危险工具

• **禁止 KEYS ***：仅允许 SCAN

• 只读模式：REDIS_READ_ONLY=true 时拒绝所有写操作

• Key 前缀隔离：防止访问非 MCP 业务数据

• 敏感信息过滤：server info 不返回密码等字段

• stdio 安全：日志仅写入 stderr，stdout 仅用于 MCP 协议

生产环境建议创建权限受限的 Redis ACL 用户，不要使用管理员账户。
默认建议开启 REDIS_READ_ONLY=true。
建议配置 REDIS_KEY_PREFIX，避免访问非 MCP 业务数据。
stdio 模式下 stdout 只能用于 MCP 协议通信。

环境要求

• Node.js >= 20

• pnpm

• Redis >= 6（测试推荐 Docker）

安装

git clone <repo>
cd redis-mcp-server
pnpm install
pnpm build

全局 CLI（可选）：

pnpm link --global
# 或 npm install -g .

启动 Redis（测试）

docker compose up -d
# 测试 Redis: redis://127.0.0.1:6380

环境变量

复制 .env.example 为 .env 并按需修改。

本地开发

cp .env.example .env
pnpm dev

构建

pnpm build
pnpm start

测试

# 单元测试
pnpm test:unit

# 集成测试（需 Redis）
docker compose up -d
pnpm test:integration
docker compose down

MCP Inspector 调试

pnpm inspector

MCP Tools 列表

系统

Key

String

Hash

List

Set

Sorted Set

Stream

Pub/Sub

批量

MCP Resources

Key 前缀

设置 REDIS_KEY_PREFIX=agentdesk: 后，调用 redis_get key="session:001" 实际访问 agentdesk:session:001。扫描结果自动去除前缀，无法通过 ../ 或通配符绕过。

只读模式

REDIS_READ_ONLY=true 时，所有写工具（set、delete、expire、hash_set、list_push 等）返回 READ_ONLY_MODE 错误。

删除权限

REDIS_ALLOW_DELETE=true 且非只读模式时，redis_delete 和 batch 中的 delete 操作才可用。默认使用 UNLINK。

MCP Host 配置

Claude Desktop / Cursor（绝对路径）

{
  "mcpServers": {
    "redis": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/redis-mcp-server/dist/index.js"
      ],
      "env": {
        "REDIS_URL": "redis://127.0.0.1:6379",
        "REDIS_KEY_PREFIX": "mcp:",
        "REDIS_READ_ONLY": "true",
        "REDIS_ALLOW_DELETE": "false"
      }
    }
  }
}

CLI 安装后

{
  "mcpServers": {
    "redis": {
      "command": "redis-mcp",
      "env": {
        "REDIS_URL": "redis://127.0.0.1:6379",
        "REDIS_READ_ONLY": "true"
      }
    }
  }
}

Codex MCP

在 Codex 配置中添加与上述相同的 mcpServers 条目。

Docker

构建镜像：

docker build -t redis-mcp-server .

运行（需外部 Redis）：

docker run -e REDIS_URL=redis://host.docker.internal:6379 redis-mcp-server

常见问题

Q: MCP Host 无法连接？
确认 dist/index.js 路径正确，Redis 可访问，环境变量已配置。

Q: 写操作被拒绝？
检查 REDIS_READ_ONLY 是否为 true。

Q: 看不到日志？
stdio 模式下日志在 stderr，不会出现在 stdout。

使用须知

使用、修改或分发本项目时，请遵守以下要求：

1. 注明作者与出处：保留作者 wangmiaozero，并标明项目来源 redis-mcp-server

2. 合法使用：不得将本项目用于任何违反法律法规的用途

开源协议

本项目采用 MIT License 开源。

MIT License

Copyright (c) 2026 wangmiaozero

允许：

• 商业使用

• 修改与衍生

• 分发

• 私有使用

条件：

• 保留作者姓名、版权声明和许可全文

• 注明项目出处（见上方使用须知）

免责：

• 软件按「原样」提供，不提供任何明示或暗示担保；作者不对任何索赔或损害负责。

完整条款见仓库根目录 LICENSE 文件。