# redis-mcp-server

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

> **语言 / Languages：** **中文** · [English (US)](README.en-US.md) · [Français](README.fr.md) · [Русский](README.ru.md) · [한국어](README.ko.md)

## 功能

- 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）

## 安装

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

全局 CLI（可选）：

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

## 启动 Redis（测试）

```bash
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` 并按需修改。

## 本地开发

```bash
cp .env.example .env
pnpm dev
```

## 构建

```bash
pnpm build
pnpm start
```

## 测试

```bash
# 单元测试
pnpm test:unit

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

## MCP Inspector 调试

```bash
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（绝对路径）

```json
{
  "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 安装后

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

### Codex MCP

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

## Docker

构建镜像：

```bash
docker build -t redis-mcp-server .
```

运行（需外部 Redis）：

```bash
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](https://github.com/wangmiaozero/redis-mcp-server)
2. **合法使用**：不得将本项目用于任何违反法律法规的用途

## 开源协议

本项目采用 [MIT License](LICENSE) 开源。

```
MIT License

Copyright (c) 2026 wangmiaozero
```

**允许：**

- 商业使用
- 修改与衍生
- 分发
- 私有使用

**条件：**

- 保留作者姓名、版权声明和许可全文
- 注明项目出处（见上方使用须知）

**免责：**

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

完整条款见仓库根目录 [LICENSE](LICENSE) 文件。