What is Redis MCP Server

The Redis MCP Server is a natural language interface designed for managing and querying data in Redis, allowing efficient interaction with structured and unstructured data through an intuitive language-driven approach. It integrates with MCP clients to facilitate AI-driven workflows and can handle a variety of data structures supported by Redis.

Use cases

The Redis MCP Server can be utilized in several applications including AI assistants that retrieve and store data, chatbots that manage session information and personalize responses, real-time data search and analytics, and event processing systems that manage streams of data efficiently.

How to use

To use the Redis MCP Server, clone the repository, install dependencies using the uv tool, and configure your environment variables. You can run the server locally with default settings or configure it to use network transport like SSE. Integration with other tools like OpenAI Agents SDK or Claude Desktop is also supported for enhanced functionality.

Key features

Key features of the Redis MCP Server include natural language query capabilities, seamless integration with MCP clients, full support for Redis data structures, efficient data retrieval and searching, and tools for managing data in Redis, including string, list, hash, set, sorted set, streams, and JSON functionalities.

Where to use

The Redis MCP Server is particularly useful in scenarios requiring fast data access and management, including AI-driven applications, enterprise chatbots, real-time analytics systems, and environments where event sourcing or activity feed processing occurs. It is ideal for developers looking to harness the power of Redis with natural language interfaces.

Redis MCP Server

Overview

The Redis MCP Server is a natural language interface designed for agentic applications to efficiently manage and search data in Redis. It integrates seamlessly with MCP (Model Content Protocol) clients, enabling AI-driven workflows to interact with structured and unstructured data in Redis. Using this MCP Server, you can ask questions like:

• “Store the entire conversation in a stream”
• “Cache this item”
• “Store the session with an expiration time”
• “Index and search this vector”

Features

• Natural Language Queries: Enables AI agents to query and update Redis using natural language.
• Seamless MCP Integration: Works with any MCP client for smooth communication.
• Full Redis Support: Handles hashes, lists, sets, sorted sets, streams, and more.
• Search & Filtering: Supports efficient data retrieval and searching in Redis.
• Scalable & Lightweight: Designed for high-performance data operations.

Tools

This MCP Server provides tools to manage the data stored in Redis.

• string tools to set, get strings with expiration. Useful for storing simple configuration values, session data, or caching responses.
• hash tools to store field-value pairs within a single key. The hash can store vector embeddings. Useful for representing objects with multiple attributes, user profiles, or product information where fields can be accessed individually.
• list tools with common operations to append and pop items. Useful for queues, message brokers, or maintaining a list of most recent actions.
• set tools to add, remove and list set members. Useful for tracking unique values like user IDs or tags, and for performing set operations like intersection.
• sorted set tools to manage data for e.g. leaderboards, priority queues, or time-based analytics with score-based ordering.
• pub/sub functionality to publish messages to channels and subscribe to receive them. Useful for real-time notifications, chat applications, or distributing updates to multiple clients.
• streams tools to add, read, and delete from data streams. Useful for event sourcing, activity feeds, or sensor data logging with consumer groups support.
• JSON tools to store, retrieve, and manipulate JSON documents in Redis. Useful for complex nested data structures, document databases, or configuration management with path-based access.

Additional tools.

• query engine tools to manage vector indexes and perform vector search
• server management tool to retrieve information about the database

Installation

Follow these instructions to install the server.

# 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

Configuration

To configure this Redis MCP Server, consider the following environment variables:

There are several ways to set environment variables:

1. Using a .env File:
   Place a .env file in your project directory with key-value pairs for each environment variable. Tools like python-dotenv, pipenv, and uv can automatically load these variables when running your application. This is a convenient and secure way to manage configuration, as it keeps sensitive data out of your shell history and version control (if .env is in .gitignore).

For example, create a .env file with the following content from the .env.example file provided in the repository:

cp .env.example .env

Then edit the .env file to set your Redis configuration:

OR,

2. Setting Variables in the Shell:
   You can export environment variables directly in your shell before running your application. For example:

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

This method is useful for temporary overrides or quick testing.

Transports

This MCP server can be configured to handle requests locally, running as a process and communicating with the MCP client via stdin and stdout.
This is the default configuration. The sse transport is also configurable so the server is available over the network.
Configure the MCP_TRANSPORT variable accordingly.

export MCP_TRANSPORT="sse"

Then start the server.

uv run src/main.py

Test the server:

curl -i http://127.0.0.1:8000/sse
HTTP/1.1 200 OK

Integrate with your favorite tool or client. The VS Code configuration for GitHub Copilot is:

"mcp": {
    "servers": {
        "redis-mcp": {
            "type": "sse",
            "url": "http://127.0.0.1:8000/sse"
        },
    }
},

Integration with OpenAI Agents SDK

Integrate this MCP Server with the OpenAI Agents SDK. Read the documents to learn more about the integration of the SDK with MCP.

Install the Python SDK.

pip install openai-agents

Configure the OpenAI token:

export OPENAI_API_KEY="<openai_token>"

And run the application.

python3.13 redis_assistant.py

You can troubleshoot your agent workflows using the OpenAI dashboard.

Integration with Claude Desktop

Via Smithery

If you’d like to test the Redis MCP Server deployed by Smithery, you can configure Claude Desktop automatically:

npx -y @smithery/cli install @redis/mcp-redis --client claude

Follow the prompt and provide the details to configure the server and connect to Redis (e.g. using a Redis Cloud database).
The procedure will create the proper configuration in the claude_desktop_config.json configuration file.

Manual configuration

You can configure Claude Desktop to use this MCP Server.

1. Specify your Redis credentials and TLS configuration
2. Retrieve your uv command full path (e.g. which uv)
3. Edit the claude_desktop_config.json configuration file
   • on a MacOS, at ~/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_CA_PATH": "<your_redis_ca_path>",
                "REDIS_CLUSTER_MODE": True|False
            }
        }
    }
}

Using with Docker

You can use a dockerized deployment of this server. You can either build your own image or use the official Redis MCP Docker image.

If you’d like to build your own image, the Redis MCP Server provides a Dockerfile. Build this server’s image with:

docker build -t mcp-redis .

Finally, configure Claude Desktop to create the container at start-up. Edit the claude_desktop_config.json and add:

{
  "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"]
    }
  }
}

To use the official Redis MCP Docker image, just replace your image name (mcp-redis in the example above) with mcp/redis.

Troubleshooting

You can troubleshoot problems by tailing the log file.

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

Integration with VS Code

To use the Redis MCP Server with VS Code, you need:

1. Enable the agent mode tools. Add the following to your settings.json:

{
  "chat.agent.enabled": true
}

2. Add the Redis MCP Server configuration to your mcp.json or settings.json:

// Example .vscode/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>",
      }
    }
  }
}

// Example settings.json
{
  "mcp": {
    "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>",
        }
      }
    }
  }
}

For more information, see the VS Code documentation.

Testing

You can use the MCP Inspector for visual debugging of this MCP Server.

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

Example Use Cases

• AI Assistants: Enable LLMs to fetch, store, and process data in Redis.
• Chatbots & Virtual Agents: Retrieve session data, manage queues, and personalize responses.
• Data Search & Analytics: Query Redis for real-time insights and fast lookups.
• Event Processing: Manage event streams with Redis Streams.

Contributing

1. Fork the repo
2. Create a new branch (feature-branch)
3. Commit your changes
4. Push to your branch and submit a PR!

License

This project is licensed under the MIT License.

Badges

Contact

For questions or support, reach out via GitHub Issues.