@qdkj/redis-mcp-server

Redis 数据库操作 MCP 服务端 · 通过 MCP 协议让 AI 客户端直接查询/操作你的 Redis

1. 🚀 MCP 使用方法 + JSON 配置

把这个 JSON 整段粘到你 MCP 客户端（Cursor / Claude Desktop / CodeBuddy 等）的配置里即可使用。npx -y @qdkj/redis-mcp-server@latest 会在首次启动时自动拉取最新版本。

最简 JSON

{
  "mcpServers": {
    "redis-exec-qdkj": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@qdkj/redis-mcp-server@latest"],
      "env": {
        "REDIS_HOST": "你的Redis地址",
        "REDIS_PORT": "6379",
        "REDIS_PASSWORD": "你的Redis密码",
        "REDIS_DATABASE": "你的数据库编号"
      }
    }
  }
}

把 env 里 你的xxx 改成自己的 Redis 信息即可。REDIS_PASSWORD 留空表示无密码。

环境变量完整说明

| 变量 | 必填 | 默认 | 说明 | |------|------|------|------| | REDIS_HOST | ✅ | — | Redis 主机 | | REDIS_PORT | | 6379 | Redis 端口 | | REDIS_PASSWORD | | 空 | Redis 密码（无密码则留空字符串） | | REDIS_DATABASE | | 0 | 数据库编号 0~15 |

工具与客户端通信

服务通过 stdio 与 MCP 客户端通信，所有日志写到 stderr，不污染 stdout。

2. 🛠️ 工具列表

服务对外暴露 10 个 MCP 工具。

2.1 list_keys

• 功能：列出 Redis 中符合匹配模式的键
• 参数：
  • pattern（可选）：匹配模式，支持通配符，默认 *
  • count（可选）：最大返回数量，默认 100
• 返回：JSON 字符串数组

2.2 get_value

• 功能：获取指定键的值（自动按类型解析 string / list / set / hash / zset）
• 参数：key（必填）
• 返回：JSON 对象，含 key / type / ttl / value

2.3 set_value

• 功能：设置键值对
• 参数：
  • key（必填）
  • value（必填）
  • ttl（可选）：过期秒数，不设置则永久

2.4 delete_key

• 功能：删除一个或多个键
• 参数：keys（必填）：多个键用逗号分隔

2.5 get_hash

• 功能：获取 Hash 类型的所有字段和值
• 参数：key（必填）
• 返回：JSON 对象（field → value）

2.6 set_hash

• 功能：设置 Hash 类型字段值
• 参数：key / field / value（均必填）

2.7 get_list

• 功能：获取 List 类型所有元素
• 参数：key（必填）
• 返回：JSON 字符串数组

2.8 get_set

• 功能：获取 Set 类型所有成员
• 参数：key（必填）
• 返回：JSON 字符串数组

2.9 get_key_info

• 功能：获取键的类型与剩余 TTL
• 参数：key（必填）

2.10 execute_command

• 功能：执行 Redis 命令（受限子集）
• 参数：command（必填），如 GET mykey / SET mykey value
• 安全约束：危险命令会被拦截（见下）

🛡️ 禁止执行的命令

以下命令被自动拦截，工具不会执行：

FLUSHDB · FLUSHALL · CONFIG RESETSTAT · SHUTDOWN · BGSAVE · BGREWRITEAOF · DEBUG · CLUSTER

execute_command 支持的命令子集：

GET · SET · DEL · KEYS · TYPE · TTL · EXISTS · HGET · HGETALL · HSET · LRANGE · SMEMBERS · INCR · DECR

3. 💻 本地调试

3.1 全局安装直接调用（推荐）

npm install -g @qdkj/redis-mcp-server --registry=https://registry.npmjs.org/

qdkj-redis-mcp-server
# 应进入 stdio 监听，Ctrl+C 退出

3.2 源码本地构建

git clone <本仓库>
cd db/redis/redis_exec_node
npm install
npm run build

# 方式 A
node dist/index.js
# 方式 B（需 tsx）
npx tsx src/index.ts

3.3 MCP 客户端调试技巧

• 日志走 stderr；想验证 JSON 配置可单独启一次服务手敲 JSON-RPC
• 想确认工具注册：让 AI 客户端列出可用工具，应看到上述 10 个

4. 🔧 二次开发

⚠️ 本 npm 包只包含编译产物 dist/ 和 README.md，不含源码。源码在 GitHub 仓库的 db/redis/redis_exec_node/src/ 下，便于二次开发但不影响安装速度。

4.1 仓库结构

db/redis/redis_exec_node/
├── src/                 # TypeScript 源码（编译前）
│   ├── config.ts        # 环境变量解析、stderr 日志
│   ├── redis.ts         # ioredis 操作 + 危险命令黑名单
│   ├── server.ts        # 10 个工具注册到 MCP Server
│   └── index.ts         # 入口（含 shebang）
├── dist/                # 编译产物（npm 包内）
├── package.json         # 1.0.3
└── README.md            # 本文件

4.2 改完如何打包并测试

cd db/redis/redis_exec_node
npm install
npm run build

# 本地测试：把你的 mcp_config.json 里 command 改成 node，args 指向新 dist/index.js

4.3 发布新版本

参考仓库根 PUBLISH.md —— npm publish --registry=https://registry.npmjs.org/ --access public，token 已配置在 ~/.npmrc。

⚠️ 注意事项

• 确保 Redis 服务可连
• 环境变量必须正确设置，否则服务启动失败
• 危险命令会被 execute_command 工具自动拦截
• execute_command 仅支持常用命令子集，完整 Redis 功能请用原生客户端
• 日志通过 stderr 输出，不影响 MCP 协议（stdout）通信

版本 1.0.3 · 最后更新 2026-08-13