Redis MCP Server

Read-only Redis AI Assistant for Qoder IDE — 面向研发团队的 Redis AI 助手

---

项目简介

Redis MCP Server 是基于 MCP (Model Context Protocol) 协议构建的 只读 Redis AI 助手，专为 Qoder IDE 设计。它通过 stdio 传输层为 AI Agent 提供安全、可控、语义化的 Redis 访问能力。

核心价值

• 降低 Redis 排障成本 — AI 辅助分析 Key 分布、内存热点、慢查询
• 提升 AI 理解基础设施能力 — 语义化工具替代手工 redis-cli
• 建立安全可控的 AI-Redis 交互入口 — 只读 + 命令白名单 + Key 前缀过滤 + 数据脱敏 + 审计日志

适用场景

场景	示例对话
排查缓存问题	"帮我分析一下 order:* 这批 Key 的 TTL 分布"
定位大 Key	"Redis 内存占用太高，帮我找出 Top 10 大 Key"
慢查询分析	"最近 Redis 响应慢，帮我看看慢查询日志"
Key 设计评审	"分析一下 session:* 的内存和过期策略"
缓存方案设计	"我要设计一个用户画像缓存，给个方案建议"

---

8 个语义化工具

工具名	功能	说明
redis_inspect_key	Key 检查	查看 Key 的类型、TTL、内存占用、大小、值预览
redis_search_keys	Key 搜索	基于 SCAN 的 Key 名称搜索（禁止 KEYS）
redis_analyze_key_pattern	Pattern 分析	采样分析某类 Key 的 TTL/大小分布，识别风险
redis_health_check	健康检查	Redis 实例状态：内存、连接数、QPS、命中率
redis_memory_analysis	内存分析	采样识别大 Key 和内存热点，Top 10 排行
redis_slowlog_analysis	慢查询分析	分析 SLOWLOG，自动生成优化建议
redis_cache_advisor	缓存建议	基于场景描述的缓存设计方案（不访问 Redis）
redis_readonly_query	只读查询	有限枚举命令（HLEN/LLEN/SCARD/ZCARD/STRLEN 等）

---

安全设计

本项目采用纵深防御策略，确保生产 Redis 安全：

安全层	机制	说明
只读访问	命令白名单	仅允许 GET/TYPE/TTL/SCAN/INFO 等只读命令
Key 前缀白名单	环境变量配置	限制可访问的 Key 前缀（如 cache:*,user:*）
数据脱敏	自动脱敏	手机号/邮箱/身份证/密码字段自动脱敏
返回大小限制	自动截断	大 Value 自动截断（默认 2000 字符）
速率限制	令牌桶	单实例 20 QPS，SCAN 操作 5 QPS
审计日志	全链路追踪	每次 Tool 调用记录完整审计信息

注意：V1.0 仅支持只读操作，所有写命令（SET/DEL/EXPIRE 等）均被拒绝。

---

架构

Qoder IDE (MCP Host)
    │
    │ stdio (stdin/stdout JSON-RPC 2.0)
    ▼
Redis MCP Server (Python)
    ├── Tool Layer        — 8 个语义化 MCP Tool
    ├── Security Guard    — 白名单 + 脱敏 + 截断 + 限流
    ├── Redis Adapter     — 连接池 + 超时 + 健康检查
    └── Observability     — structlog 日志 + 审计日志
            │
            │ redis-py (async)
            ▼
    Redis (单机/Cluster >= 6.0)

---

安装

通过 pip（推荐）

pip install as-redis-mcp-server

通过 uvx（零安装）

uvx --from as-redis-mcp-server@latest as-redis-mcp-server

从源码安装

git clone <repository-url>
cd redis-mcp
pip install -e ".[dev]"

---

配置

环境变量

变量名	说明	默认值
REDIS_HOST	Redis 主机地址	127.0.0.1
REDIS_PORT	Redis 端口	6379
REDIS_DB	Redis 数据库编号	0
REDIS_USERNAME	Redis 用户名（ACL）	default
REDIS_PWD	Redis 密码	（空）
REDIS_SSL	是否启用 SSL/TLS	false
REDIS_SSL_CA_CERTS	CA 证书路径	（空）
REDIS_CLUSTER_MODE	是否集群模式	false
REDIS_MAX_CONNECTIONS	连接池上限	20
REDIS_SOCKET_TIMEOUT	命令超时（秒）	3
REDIS_CONNECT_TIMEOUT	连接超时（秒）	3
KEY_PREFIX_WHITELIST	Key 前缀白名单（逗号分隔 glob）	（空=全部允许）
MAX_SCAN_COUNT	SCAN 单次迭代 COUNT	100
MAX_VALUE_LENGTH	返回值最大字符数	2000
RATE_LIMIT_QPS	全局 QPS 限制	20
MCP_REDIS_LOG_LEVEL	日志级别	INFO

Redis ACL 配置（推荐）

生产环境建议使用只读账号：

ACL SETUSER mcp_reader on ><your-password> ~* +@read -@write -@admin -@dangerous

---

Qoder IDE 配置

方式一：uvx 零安装（推荐）

在 Qoder 的 MCP 配置文件中添加：

{
  "mcpServers": {
    "redis-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "as-redis-mcp-server@latest",
        "as-redis-mcp-server"
      ],
      "env": {
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "REDIS_PWD": "<your-redis-password>",
        "KEY_PREFIX_WHITELIST": "cache:*,session:*,user:*,order:*",
        "MCP_REDIS_LOG_LEVEL": "INFO"
      }
    }
  }
}

说明：uvx 方式会自动从 PyPI 下载最新版本并运行，无需手动安装。需先安装 uv。

方式二：pip 全局安装

pip install as-redis-mcp-server

然后在 Qoder MCP 配置中添加：

{
  "mcpServers": {
    "redis-mcp": {
      "type": "stdio",
      "command": "as-redis-mcp-server",
      "env": {
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "REDIS_PWD": "<your-redis-password>",
        "KEY_PREFIX_WHITELIST": "cache:*,session:*,user:*,order:*",
        "MCP_REDIS_LOG_LEVEL": "INFO"
      }
    }
  }
}

方式三：本地开发（pip install -e）

git clone <repository-url>
cd redis-mcp
pip install -e ".[dev]"

Qoder MCP 配置：

{
  "mcpServers": {
    "redis-mcp": {
      "type": "stdio",
      "command": "as-redis-mcp-server",
      "cwd": "/path/to/redis-mcp",
      "env": {
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "REDIS_PWD": "<your-redis-password>",
        "KEY_PREFIX_WHITELIST": "cache:*,session:*,user:*,order:*"
      }
    }
  }
}

方式四：Docker

FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir as-redis-mcp-server
ENTRYPOINT ["as-redis-mcp-server"]

Key 前缀白名单配置说明

KEY_PREFIX_WHITELIST 控制 AI 可访问的 Key 前缀，使用 glob 模式，逗号分隔：

配置值	效果
（空/不设置）	允许所有 Key（仅开发环境）
cache:*,session:*	仅允许 cache: 和 session: 开头的 Key
user:*,order:*,product:*	允许三类业务 Key

安全建议：生产环境必须配置 Key 前缀白名单，避免 AI 访问不相关的 Key 空间。

---

快速验证

启动 MCP Server

# 直接启动（需先设置环境变量或 .env 文件）
export REDIS_HOST=127.0.0.1
export REDIS_PORT=6379
as-redis-mcp-server

使用 MCP Inspector 调试

npx @modelcontextprotocol/inspector as-redis-mcp-server

运行测试

pip install -e ".[dev]"
pytest tests/ -v

---

技术栈

组件	版本	说明
Python	>= 3.12	运行时
FastMCP	>= 2.0	MCP 框架
redis-py	>= 5.0 (含 hiredis)	Redis 异步客户端
Pydantic	>= 2.0	Schema 验证
pydantic-settings	>= 2.0	环境变量配置管理
structlog	>= 24.0	结构化日志

---

项目结构

redis-mcp-server/
├── pyproject.toml          # 项目元数据与依赖
├── Dockerfile              # 容器化部署
├── README.md               # 本文档
├── src/
│   ├── main.py             # 入口点
│   ├── server.py           # Tool 注册（@mcp.tool()）
│   ├── config.py           # 配置管理（pydantic-settings）
│   ├── errors.py           # 统一错误模型
│   ├── mcp/server.py       # FastMCP 实例 + 生命周期
│   ├── tools/              # 8 个 MCP Tool 实现
│   ├── redis_client/       # 连接池 + SCAN + 分析器
│   ├── security/           # 白名单 + 脱敏 + 截断 + 限流
│   ├── models/schema.py    # Pydantic 模型
│   └── observability/      # structlog + 审计日志
└── tests/                  # pytest 测试套件

---

License

MIT