Redis MCP Server

Redis MCP 服务

概述

Redis MCP 服务是一种自然语言接口，旨在帮助 Agent 应用高效地管理和搜索 Redis 中的数据。它可与 MCP（Model Content Protocol）客户端无缝集成，让 AI 驱动的工作流能够与 Redis 中的结构化和非结构化数据交互。使用此 MCP 服务，你可以提出如下请求：

• “将整个对话存储到流中”
• “缓存此项目”
• “存储会话并设置过期时间”
• “为此向量建立索引并进行搜索”

目录

• 概述
• 功能
• 工具
• 安装
  • 从 PyPI 安装（推荐）
  • 测试 PyPI 软件包
  • 从 GitHub 安装
  • 开发环境安装
  • 使用 Docker
• 配置
  • Redis ACL
  • 通过命令行参数配置
  • 通过环境变量配置
  • Azure Managed Redis 的 EntraID 身份验证
  • 日志记录
• 集成
  • OpenAI Agents SDK
  • Augment
  • Claude Desktop
  • VS Code 和 GitHub Copilot
• 测试
• 示例用例
• 贡献
• 许可证
• 徽章
• 联系

功能

• 自然语言查询：让 AI Agent 能够使用自然语言查询和更新 Redis。
• 无缝集成 MCP：可与任何 MCP 客户端配合使用，实现流畅通信。
• 全面支持 Redis：支持哈希、列表、集合、有序集合、流等。
• 搜索与筛选：支持在 Redis 中高效检索和搜索数据。
• 可扩展且轻量：专为高性能数据操作而设计。
• EntraID 身份验证：原生支持通过 Azure Active Directory 对 Azure Managed Redis 进行身份验证。
• Redis MCP 服务支持 stdio 传输方式。未来将添加对 stremable-http 传输方式的支持。

工具

此 MCP 服务提供用于管理存储在 Redis 中的数据的工具。

• string 工具，用于设置和获取带过期时间的字符串。适用于存储简单的配置值、会话数据或缓存响应。
• hash 工具，用于在单个键中存储字段-值对。哈希可以存储向量嵌入。适用于表示包含多个属性的对象、用户资料或可单独访问字段的产品信息。
• list 工具，支持追加和弹出项目等常见操作。适用于队列、消息代理，或维护最近操作的列表。
• set 工具，用于添加、移除和列出集合成员。适用于跟踪用户 ID 或标签等唯一值，以及执行交集等集合操作。
• sorted set 工具，用于管理排行榜、优先级队列或基于时间的分析等数据，并按分数排序。
• pub/sub 功能，用于发布消息、创建有状态的频道或模式订阅，并使用返回的订阅句柄读取排队的消息。适用于实时通知、聊天应用或向多个客户端分发更新。
• streams 工具，用于在数据流中添加、读取、删除数据，创建和销毁消费者组，并确认已处理的条目。适用于事件溯源、活动动态，以及使用 Redis Streams 消费者组进行基于工作进程的事件处理。
• JSON 工具，用于在 Redis 中存储、检索和操作 JSON 文档。适用于复杂的嵌套数据结构、文档数据库或基于路径的配置管理。

其他工具。

• docs 工具，可通过自然语言问题搜索 Redis 文档、教程和最佳实践（由 MCP_DOCS_SEARCH_URL HTTP API 提供支持）。
• query engine 工具，用于管理向量索引并执行向量搜索。
• server management 工具，用于获取数据库信息。

安装

Redis MCP Server 可作为 PyPI 包使用，也可直接从 GitHub 仓库安装。

从 PyPI 安装（推荐）

例如，可以将以下 JSON 配置导入所需的框架或工具，以配置最新版本的 Redis MCP Server。 uvx 命令会按需下载服务（如果尚未缓存），创建临时环境，然后运行服务。

{
  "mcpServers": {
    "RedisMCPServer": {
      "command": "uvx",
      "args": [
        "--from",
        "redis-mcp-server@latest",
        "redis-mcp-server",
        "--url",
        "\"redis://localhost:6379/0\""
      ]
    }
  }
}

URL 规范

--url 参数的格式遵循 redis 和 rediss 方案：

redis://user:secret@localhost:6379/0?foo=bar&qux=baz

例如，你可以轻松连接到本地主机上的服务：

redis://localhost:6379/0

其中，0 是你要连接的逻辑数据库。

若要通过加密连接访问数据库（例如，连接到 Redis Cloud 数据库），请使用 rediss 方案。

rediss://user:secret@localhost:6379/0?foo=bar&qux=baz

若要验证服务的身份，请指定 ssl_ca_certs。

rediss://user:secret@hostname:port?ssl_cert_reqs=required&ssl_ca_certs=path_to_the_certificate

若要进行未验证的连接，请将 ssl_cert_reqs 设置为 none。

rediss://user:secret@hostname:port?ssl_cert_reqs=none

请使用“可用的 CLI 选项”一节中的选项配置连接。

测试 PyPI 包

你可以按如下方式安装该包：

pip install redis-mcp-server

然后使用环境中的 uv 启动该包。

uv python install 3.14
uv sync
uv run redis-mcp-server --url redis://localhost:6379/0

不过，将 MCP Server 的启动委托给配置了此 MCP Server 的框架或工具会更加实用。

来自 GitHub

你可以使用 uvx 配置所需的 Redis MCP Server 版本，从 GitHub 直接运行它（可以指定分支，也可以使用带标签的发行版）。

建议使用带标签的发行版；main 分支仍在积极开发中，可能包含不兼容的更改。

例如，你可以运行以下命令来运行 0.2.0 版本：

uvx --from git+https://github.com/redis/[email protected] redis-mcp-server --url redis://localhost:6379/0

请查看 Releases 部分中的最新版本说明。 下方提供了更多示例。

# Run with Redis URI
uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --url redis://localhost:6379/0

# Run with Redis URI and SSL
uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --url "rediss://<USERNAME>:<PASSWORD>@<HOST>:<PORT>?ssl_cert_reqs=required&ssl_ca_certs=<PATH_TO_CERT>"

# Run with individual parameters
uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --host localhost --port 6379 --password mypassword

# See all options
uvx --from git+https://github.com/redis/mcp-redis.git redis-mcp-server --help

开发安装

如果用于开发，或者你更喜欢克隆仓库：

# Clone the repository
git clone https://github.com/redis/mcp-redis.git
cd mcp-redis

# Install dependencies using uv
uv venv
source .venv/bin/activate
uv sync

# Run with CLI interface
uv run redis-mcp-server --help

# Or run the main file directly (uses environment variables)
uv run src/main.py

克隆仓库、安装依赖项并确认可以运行服务后，你可以配置 Claude Desktop 或其他 MCP 客户端，让其直接运行主文件来使用此 MCP 服务（它使用环境变量）。开发时通常推荐这种方式。 以下示例适用于 Claude Desktop，但同样适用于其他 MCP 客户端。

1. 指定 Redis 凭据和 TLS 配置
2. 获取 uv 命令的完整路径（例如 which uv）
3. 编辑 claude_desktop_config.json 配置文件
   • 在 MacOS 上，路径为 ~/Library/Application\ Support/Claude/

{
    "mcpServers": {
        "redis": {
            "command": "<full_path_uv_command>",
            "args": [
                "--directory",
                "<your_mcp_server_directory>",
                "run",
                "src/main.py"
            ],
            "env": {
                "REDIS_HOST": "<your_redis_database_hostname>",
                "REDIS_PORT": "<your_redis_database_port>",
                "REDIS_PWD": "<your_redis_database_password>",
                "REDIS_SSL": True|False,
                "REDIS_SSL_CA_PATH": "<your_redis_ca_path>",
                "REDIS_CLUSTER_MODE": True|False
            }
        }
    }
}

你可以通过查看日志文件来排查问题。

tail -f ~/Library/Logs/Claude/mcp-server-redis.log

使用 Docker

你可以使用 Docker 部署此服务。你可以自行构建镜像，也可以使用官方的 Redis MCP Docker 镜像。

如果你想自行构建镜像，Redis MCP Server 提供了一个 Dockerfile。使用以下命令构建此服务的镜像：

docker build -t mcp-redis .

最后，配置客户端以便在启动时创建容器。下面提供了 Claude Desktop 示例。编辑 claude_desktop_config.json 并添加：

{
  "mcpServers": {
    "redis": {
      "command": "docker",
      "args": ["run",
                "--rm",
                "--name",
                "redis-mcp-server",
                "-i",
                "-e", "REDIS_HOST=<redis_hostname>",
                "-e", "REDIS_PORT=<redis_port>",
                "-e", "REDIS_USERNAME=<redis_username>",
                "-e", "REDIS_PWD=<redis_password>",
                "mcp-redis"]
    }
  }
}

要使用官方的 Redis MCP Docker 镜像，只需将镜像名称（上例中的 mcp-redis）替换为 mcp/redis。

配置

Redis MCP Server 可以通过两种方式配置：命令行参数或环境变量。 优先级顺序为：命令行参数 > 环境变量 > 默认值。

Redis ACL

你可以配置 Redis ACL 来限制对 Redis 数据库的访问。例如，创建一个只读用户：

127.0.0.1:6379> ACL SETUSER readonlyuser on >mypassword ~* +@read -@write

通过命令行参数或环境变量配置该用户。

通过命令行参数配置

使用 CLI 界面时，你可以通过命令行参数配置服务：

# Basic Redis connection
uvx --from redis-mcp-server@latest redis-mcp-server \
  --host localhost \
  --port 6379 \
  --password mypassword

# Using Redis URI (simpler)
uvx --from redis-mcp-server@latest redis-mcp-server \
  --url redis://user:pass@localhost:6379/0

# SSL connection
uvx --from redis-mcp-server@latest redis-mcp-server \
  --url rediss://user:[email protected]:6379/0

# See all available options
uvx --from redis-mcp-server@latest redis-mcp-server --help

可用的 CLI 选项：

• --url - Redis 连接 URI（redis://user:pass@host:port/db）
• --host - Redis 主机名（默认值：127.0.0.1）
• --port - Redis 端口（默认值：6379）
• --db - Redis 数据库编号（默认值：0）
• --username - Redis 用户名
• --password - Redis 密码
• --ssl - 启用 SSL 连接
• --ssl-ca-path - CA 证书文件路径
• --ssl-keyfile - SSL 密钥文件路径
• --ssl-certfile - SSL 证书文件路径
• --ssl-cert-reqs - SSL 证书要求（默认值：required）
• --ssl-ca-certs - CA 证书文件路径
• --cluster-mode - 启用 Redis 集群模式

通过环境变量进行配置

如有需要，您可以使用环境变量。所有变量均提供默认值。

名称	描述	默认值
REDIS_HOST	Redis IP 或主机名	"127.0.0.1"
REDIS_PORT	Redis 端口	6379
REDIS_DB	数据库	0
REDIS_USERNAME	默认数据库用户名	"default"
REDIS_PWD	默认数据库密码	""
REDIS_SSL	启用或禁用 SSL/TLS	False
REDIS_SSL_CA_PATH	用于验证服务端的 CA 证书	None
REDIS_SSL_KEYFILE	用于客户端身份验证的客户端私钥文件	None
REDIS_SSL_CERTFILE	用于客户端身份验证的客户端证书文件	None
REDIS_SSL_CERT_REQS	客户端是否应验证服务端证书	"required"
REDIS_SSL_CA_CERTS	受信任 CA 证书文件的路径	None
REDIS_CLUSTER_MODE	启用 Redis Cluster 模式	False

Azure Managed Redis 的 EntraID 身份验证

Redis MCP 服务支持 Azure Managed Redis 的 EntraID（Azure Active Directory）身份验证，可通过 OAuth 身份验证并自动管理令牌。

身份验证提供程序

服务主体身份验证 - 使用客户端凭据进行基于应用程序的身份验证：

export REDIS_ENTRAID_AUTH_FLOW=service_principal
export REDIS_ENTRAID_CLIENT_ID=your-client-id
export REDIS_ENTRAID_CLIENT_SECRET=your-client-secret
export REDIS_ENTRAID_TENANT_ID=your-tenant-id

托管身份验证 - 适用于托管在 Azure 上的应用程序：

# System-assigned managed identity
export REDIS_ENTRAID_AUTH_FLOW=managed_identity
export REDIS_ENTRAID_IDENTITY_TYPE=system_assigned

# User-assigned managed identity
export REDIS_ENTRAID_AUTH_FLOW=managed_identity
export REDIS_ENTRAID_IDENTITY_TYPE=user_assigned
export REDIS_ENTRAID_USER_ASSIGNED_CLIENT_ID=your-identity-client-id

默认 Azure 凭据 - 自动发现凭据（推荐用于开发）：

export REDIS_ENTRAID_AUTH_FLOW=default_credential
export REDIS_ENTRAID_SCOPES=https://redis.azure.com/.default

EntraID 配置变量

名称	描述	默认值
REDIS_ENTRAID_AUTH_FLOW	身份验证流程类型	None（已禁用 EntraID）
REDIS_ENTRAID_CLIENT_ID	服务主体客户端 ID	None
REDIS_ENTRAID_CLIENT_SECRET	服务主体客户端密钥	None
REDIS_ENTRAID_TENANT_ID	Azure 租户 ID	None
REDIS_ENTRAID_IDENTITY_TYPE	托管身份类型	"system_assigned"
REDIS_ENTRAID_USER_ASSIGNED_CLIENT_ID	用户分配的托管身份客户端 ID	None
REDIS_ENTRAID_SCOPES	默认 Azure 凭据的 OAuth 范围	"https://redis.azure.com/.default"
REDIS_ENTRAID_RESOURCE	Azure Redis 资源标识符	"https://redis.azure.com/"

主要功能

• 自动续期令牌 - 在后台刷新令牌，无需手动干预
• 平稳回退 - 未配置 EntraID 时，回退到标准 Redis 身份验证
• 多种身份验证流程 - 支持服务主体、托管身份和默认 Azure 凭据
• 适用于企业 - 专为采用集中式身份管理的 Azure Managed Redis 设计

示例配置

使用 Azure CLI 进行本地开发：

# Login with Azure CLI
az login

# Configure MCP server
export REDIS_ENTRAID_AUTH_FLOW=default_credential
export REDIS_URL=redis://your-azure-redis.redis.cache.windows.net:6379

使用 Service Principal 进行生产部署：

export REDIS_ENTRAID_AUTH_FLOW=service_principal
export REDIS_ENTRAID_CLIENT_ID=your-app-client-id
export REDIS_ENTRAID_CLIENT_SECRET=your-app-secret
export REDIS_ENTRAID_TENANT_ID=your-tenant-id
export REDIS_URL=redis://your-azure-redis.redis.cache.windows.net:6379

使用 Managed Identity 的Azure 托管应用程序：

export REDIS_ENTRAID_AUTH_FLOW=managed_identity
export REDIS_ENTRAID_IDENTITY_TYPE=system_assigned
export REDIS_URL=redis://your-azure-redis.redis.cache.windows.net:6379

设置环境变量有几种方式：

1. 使用 .env 文件： 在项目目录中放置一个 .env 文件，其中包含每个环境变量的键值对。python-dotenv、pipenv 和 uv 等工具可以在运行应用程序时自动加载这些变量。这是一种方便且安全的配置管理方式，因为它可以避免敏感数据出现在 shell 历史记录和版本控制中（前提是 .env 已添加到 .gitignore）。 例如，使用仓库中提供的 .env.example 文件创建一个 .env 文件，内容如下：

cp .env.example .env

然后编辑 .env 文件以设置 Redis 配置：

或者，

2. 在 Shell 中设置变量： 你可以在运行应用程序之前，直接在 shell 中导出环境变量。例如：

export REDIS_HOST=your_redis_host
export REDIS_PORT=6379
# Other variables will be set similarly...

这种方式适用于临时覆盖或快速测试。

日志记录

服务使用 Python 的标准日志记录功能，并在启动时进行配置。默认情况下，它会记录 WARNING 及以上级别的日志。你可以通过 MCP_REDIS_LOG_LEVEL 环境变量更改日志详细程度。

• 支持的值（不区分大小写）：DEBUG、INFO、WARNING、ERROR、CRITICAL、NOTSET
• 支持的别名：WARN → WARNING、FATAL → CRITICAL
• 也接受数值，包括带符号的数值（例如 "10"、"+20"）
• 未设置或无法识别时的默认值：WARNING

处理器行为

• 如果宿主（例如 uv、VS Code、pytest）已安装控制台处理器，服务不会添加自己的处理器；它只会降低限制过严的处理器阈值，以确保所选级别的日志不会被过滤。它绝不会提高处理器阈值。
• 如果不存在处理器，服务会添加一个使用简单格式的 stderr StreamHandler。

示例

# See normal lifecycle messages
MCP_REDIS_LOG_LEVEL=INFO uv run src/main.py

# Very verbose for debugging
MCP_REDIS_LOG_LEVEL=DEBUG uvx --from redis-mcp-server@latest redis-mcp-server --url redis://localhost:6379/0

在支持 env 的 MCP 客户端配置中，将其与 Redis 设置一同添加。例如：

{
  "mcpServers": {
    "redis": {
      "command": "uvx",
      "args": ["--from", "redis-mcp-server@latest", "redis-mcp-server", "--url", "redis://localhost:6379/0"],
      "env": {
        "REDIS_HOST": "localhost",
        "REDIS_PORT": "6379",
        "MCP_REDIS_LOG_LEVEL": "INFO"
      }
    }
  }
}

集成

以下章节介绍如何将此 MCP 服务集成到 OpenAI Agents SDK 等开发框架中，或与 Claude Desktop、VS Code、Augment 等工具集成。

OpenAI Agents SDK

将此 MCP 服务与 OpenAI Agents SDK 集成。阅读文档以进一步了解 SDK 与 MCP 的集成。

安装 Python SDK。

pip install openai-agents

配置 OpenAI 令牌：

export OPENAI_API_KEY="<openai_token>"

然后运行应用程序。

python3.14 redis_assistant.py

你可以使用 OpenAI 控制面板排查 Agent 工作流问题。

Augment

在 Augment 中配置 Redis MCP 服务的首选方式是使用 Easy MCP 功能。

你也可以通过导入服务器的 JSON 手动配置 Augment 中的 Redis MCP 服务：

{
  "mcpServers": {
    "Redis MCP Server": {
      "command": "uvx",
      "args": [
        "--from",
        "redis-mcp-server@latest",
        "redis-mcp-server",
        "--url",
        "redis://localhost:6379/0"
      ]
    }
  }
}

Claude Desktop

配置 MCP 客户端最简单的方式是使用 uvx。将以下 JSON 添加到你的 claude_desktop_config.json 中，并记得提供 uvx 的完整路径。

基本 Redis 连接：

{
  "mcpServers": {
    "redis-mcp-server": {
        "type": "stdio",
        "command": "/Users/mortensi/.local/bin/uvx",
        "args": [
            "--from", "redis-mcp-server@latest",
            "redis-mcp-server",
            "--url", "redis://localhost:6379/0"
        ]
    }
  }
}

使用 EntraID 身份验证的 Azure Managed Redis：

{
  "mcpServers": {
    "redis-mcp-server": {
        "type": "stdio",
        "command": "/Users/mortensi/.local/bin/uvx",
        "args": [
            "--from", "redis-mcp-server@latest",
            "redis-mcp-server",
            "--url", "redis://your-azure-redis.redis.cache.windows.net:6379"
        ],
        "env": {
            "REDIS_ENTRAID_AUTH_FLOW": "default_credential",
            "REDIS_ENTRAID_SCOPES": "https://redis.azure.com/.default"
        }
    }
  }
}

使用 GitHub Copilot 的 VS Code

若要在 VS Code 中使用 Redis MCP 服务，你必须启用 Agent 模式工具。将以下内容添加到你的 settings.json：

{
  "chat.agent.enabled": true
}

你可以通过将以下 JSON 添加到 mcp.json 文件，使用 uvx 启动 GitHub 所需版本的 Redis MCP 服务：

"servers": {
  "redis": {
    "type": "stdio",
    "command": "uvx",
    "args": [
      "--from", "redis-mcp-server@latest",
      "redis-mcp-server",
      "--url", "redis://localhost:6379/0"
    ]
  },
}

隐藏 uvx 安装消息

如果你想隐藏可能作为警告出现在 MCP 客户端日志中的 uvx 安装消息，请使用 -qq 标志：

"servers": {
  "redis": {
    "type": "stdio",
    "command": "uvx",
    "args": [
      "-qq",
      "--from", "redis-mcp-server@latest",
      "redis-mcp-server",
      "--url", "redis://localhost:6379/0"
    ]
  },
}

-qq 标志会启用静默模式，隐藏 uvx 在安装软件包期间写入标准错误的“已安装 X 个软件包”消息。

或者，你可以使用 uv 启动服务并配置 mcp.json。这通常适用于开发场景。

// mcp.json
{
  "servers": {
    "redis": {
      "type": "stdio",
      "command": "<full_path_uv_command>",
      "args": [
        "--directory",
        "<your_mcp_server_directory>",
        "run",
        "src/main.py"
      ],
      "env": {
        "REDIS_HOST": "<your_redis_database_hostname>",
        "REDIS_PORT": "<your_redis_database_port>",
        "REDIS_USERNAME": "<your_redis_database_username>",
        "REDIS_PWD": "<your_redis_database_password>",
      }
    }
  }
}

如需了解更多信息，请参阅 VS Code 文档。

**提示：**你可以在消息中加入 #redis，提示 Copilot 聊天使用 Redis MCP 工具。

**注意：**从 VS Code v1.102 开始， MCP 服务现在存储在专用的 mcp.json 文件中，而不是 settings.json。

测试

你可以使用 MCP Inspector 对此 MCP 服务进行可视化调试。

npx @modelcontextprotocol/inspector uv run src/main.py

示例用例

• AI 助手：让大模型能够在 Redis 中获取、存储和处理数据。
• 聊天机器人和虚拟 Agent：检索会话数据、管理队列并个性化回复。
• 数据搜索与分析：查询 Redis，获取实时洞察并快速查找。
• 事件处理：使用 Redis Streams 管理事件流。

贡献

1. Fork 此仓库
2. 创建新分支（feature-branch）
3. 提交更改
4. 将更改推送到你的分支并提交 PR！

许可证

本项目采用 MIT License 授权。

徽章

联系方式

如有疑问或需要支持，请通过 GitHub Issues 联系我们。

或者，你可以加入 Redis Discord 服务器，并在 #redis-mcp-server 频道提问。