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

安全设计

• 禁止任意命令执行：不提供 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

环境变量

变量	默认值	说明
REDIS_URL	必填	Redis 连接 URL
REDIS_USERNAME	-	用户名
REDIS_PASSWORD	-	密码
REDIS_DATABASE	0	数据库编号
REDIS_CONNECT_TIMEOUT_MS	5000	连接超时
REDIS_COMMAND_TIMEOUT_MS	10000	命令超时
REDIS_MAX_RECONNECT_ATTEMPTS	10	最大重连次数
REDIS_KEY_PREFIX	-	Key 前缀隔离
REDIS_READ_ONLY	false	只读模式
REDIS_ALLOW_DELETE	false	允许删除
REDIS_ALLOW_PUBLISH	false	允许发布
REDIS_ALLOW_SERVER_INFO	true	允许 server info
REDIS_MAX_SCAN_COUNT	100	SCAN 单次上限
REDIS_MAX_RESULT_ITEMS	500	返回元素上限
REDIS_MAX_VALUE_BYTES	1048576	单值字节上限
REDIS_MAX_BATCH_OPERATIONS	50	批量操作上限
LOG_LEVEL	info	日志级别

复制 .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 列表

系统

工具	说明
redis_ping	检测连接
redis_server_info	过滤后的服务器信息
redis_dbsize	当前 DB Key 数量
redis_type	Key 类型

Key

工具	说明
redis_scan_keys	SCAN 扫描 Key
redis_exists	检查存在
redis_delete	删除 Key（需权限）
redis_expire	设置过期
redis_ttl	获取 TTL
redis_persist	移除过期

String

工具	说明
redis_get	获取值
redis_mget	批量获取
redis_set	设置值
redis_increment	递增/递减

Hash

工具	说明
redis_hash_get	获取字段
redis_hash_get_all	获取全部字段
redis_hash_set	设置字段
redis_hash_delete	删除字段
redis_hash_exists	字段存在检查
redis_hash_increment	字段递增
redis_hash_length	字段数量

List

工具	说明
redis_list_range	范围读取
redis_list_push	推入元素
redis_list_pop	弹出元素
redis_list_length	长度
redis_list_trim	裁剪

Set

工具	说明
redis_set_add	添加成员
redis_set_members	获取成员
redis_set_remove	移除成员
redis_set_contains	成员检查
redis_set_cardinality	成员数量
redis_set_intersection	交集
redis_set_union	并集
redis_set_difference	差集

Sorted Set

工具	说明
redis_zset_add	添加成员
redis_zset_range	范围读取
redis_zset_score	获取分数
redis_zset_remove	移除成员
redis_zset_cardinality	成员数量
redis_zset_increment	分数递增

Stream

工具	说明
redis_stream_add	添加条目
redis_stream_range	范围读取
redis_stream_reverse_range	逆序读取
redis_stream_length	长度
redis_stream_delete	删除条目

Pub/Sub

工具	说明
redis_publish	发布消息（需权限）

批量

工具	说明
redis_batch	批量操作（Pipeline / 原子事务）

MCP Resources

URI	说明
redis://status	连接与权限状态
redis://key/{key}	只读读取 Key 数据（自动前缀、类型检测、截断）

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 文件。