mcp-redis: Instructions file for Claude Code

Redis MCP Server - 项目总览

项目愿景

Redis MCP Server 是一个为 AI 智能体应用设计的自然语言接口，旨在通过 MCP (Model Context Protocol) 客户端高效管理和搜索 Redis 数据。它使 AI 驱动的工作流能够与 Redis 中的结构化和非结构化数据进行交互。

架构总览

技术栈

• 语言: Python 3.10+
• 框架: FastMCP (Model Context Protocol)
• 数据库: Redis (支持单实例和集群模式)
• 主要依赖: redis, numpy, click, dotenv

核心架构

• 服务层: 基于 FastMCP 的异步 MCP 服务器
• 连接管理: 单例模式的 Redis 连接管理器，支持 SSL/TLS 和集群
• 工具模块: 按数据类型分组的 Redis 操作工具集
• 配置系统: 灵活的配置管理，支持环境变量和命令行参数

模块结构图

graph TD
    A["(根) Redis MCP Server"] --> B["src"];
    A --> C["tests"];

    B --> D["common"];
    B --> E["tools"];
    B --> F["main.py"];
    B --> G["version.py"];

    D --> H["server.py<br/>MCP服务器核心"];
    D --> I["config.py<br/>配置管理"];
    D --> J["connection.py<br/>Redis连接管理"];
    D --> K["logging_utils.py<br/>日志工具"];

    E --> L["string.py<br/>字符串操作"];
    E --> M["hash.py<br/>哈希操作"];
    E --> N["list.py<br/>列表操作"];
    E --> O["set.py<br/>集合操作"];
    E --> P["sorted_set.py<br/>有序集合操作"];
    E --> Q["stream.py<br/>流操作"];
    E --> R["json.py<br/>JSON操作"];
    E --> S["pub_sub.py<br/>发布订阅"];
    E --> T["redis_query_engine.py<br/>向量搜索"];
    E --> U["server_management.py<br/>服务器管理"];
    E --> V["misc.py<br/>杂项操作"];
    E --> AA["redis_execute.py<br/>通用命令工具"];

    C --> W["test_*.py<br/>单元测试"];
    C --> X["tools/test_*.py<br/>工具测试"];
    C --> Y["conftest.py<br/>测试配置"];

    click H "./src/common/CLAUDE.md" "查看 common 模块文档"
    click L "./src/tools/CLAUDE.md" "查看 tools 模块文档"
    click W "./tests/CLAUDE.md" "查看 tests 模块文档"

模块索引

模块路径	职责描述	主要功能
src/main.py	应用入口点	CLI 接口，服务器启动
src/common/	核心基础设施	MCP服务器、连接管理、配置、日志
src/tools/	Redis 操作工具集	按数据类型分组的 Redis 操作
tests/	测试套件	单元测试和集成测试

运行与开发

安装和运行

# 从 PyPI 安装
pip install redis-mcp-server
redis-mcp-server --url redis://localhost:6379/0

# 开发模式
git clone https://github.com/redis/mcp-redis.git
cd mcp-redis
uv venv
source .venv/bin/activate
uv sync
uv run redis-mcp-server --help