Redis MCP Interface Server

Introduction

The Redis MCP Endpoint provides a conversational interface enabling autonomous systems to perform data management and retrieval tasks against a Redis database using ordinary language descriptions. It supports the Model Content Protocol (MCP) framework, facilitating the control over various Redis data structures such as Hashes, Lists, Sets, and Streams for sophisticated data manipulation and analytical extraction.

Common operational requests include:

"Persist the complete dialogue history within a designated stream"
"Implement a temporary cache for this object"
"Save the current user session, ensuring it has a defined Time-To-Live (TTL)"
"Catalog and execute similarity searches on this vector dataset"

Feature Set

Semantic Command Execution: Allows AI agents to issue data modification and query commands to Redis using natural language.
Standardized MCP Compliance: Guarantees interoperability with any compliant MCP client.
Comprehensive Data Type Coverage: Provides functional access to hashes, sorted sets, streams, standard sets, and more.
Advanced Filtering and Lookup: Supports granular data retrieval and pattern matching within the database.
Optimized Performance: Engineered for speed and low overhead in data transactions.
The Redis MCP Endpoint utilizes the stdio communication channel. Future updates plan to incorporate the stremable-http transport.

Provided Functionality (Tools)

This MCP service exposes specific utilities for interacting with Redis persistence layers.

string utilities for setting and fetching scalar values, including expiry management. Ideal for configuration settings, transient session storage, or caching.
hash operations for managing collections of field-value pairs under a single key, capable of indexing vector embeddings. Excellent for modeling structured records like user profiles or product manifests.
list primitives for queue-like behavior (e.g., appending, popping elements). Suited for message queuing systems or maintaining recent event logs.
set capabilities for adding, removing, and enumerating unique elements. Valuable for tracking distinct identifiers (e.g., user IDs) and executing set logic like intersections.
sorted set tools for maintaining ordered collections based on associated scores. Perfect for leaderboards, priority task queues, or time-series aggregation.
pub/sub mechanisms for real-time message broadcasting and subscription. Essential for live updates, notifications, and chat services.
streams management for sequential, append-only logs, supporting read/write/delete operations and consumer groups. Critical for event sourcing and activity tracking.
JSON utilities for full document storage, retrieval, and in-place modification using JSONPath expressions. Best for managing complex, nested data structures.

Auxiliary utilities:

vector indexer tools for managing specialized indexes and executing nearest-neighbor searches.
system monitor tool for querying operational metadata about the connected data store.

Deployment and Setup

The Redis MCP Interface is packaged via PyPI and also directly accessible via source control.

Via PyPI (Recommended Method)

To deploy the current stable version using the uvx utility, which handles fetching, environment setup, and execution on demand:

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

Docker Deployment

Pre-built images are available on Docker Hub under mcp/redis. If building locally, use the included Dockerfile:

commandline

Build custom image

docker build -t mcp-redis .

For client integration (e.g., Claude Desktop), configure it to run the container:

{ "mcpServers": { "redis": { "command": "docker", "args": ["run", "--rm", "--name", "redis-mcp-server", "-i", "-e", "REDIS_HOST=", "-e", "REDIS_PORT=", "-e", "REDIS_USERNAME=", "-e", "REDIS_PWD=", "mcp-redis"] // Or "mcp/redis" for official image } } }

Configuration Directives

Settings are prioritized: Command Line > Environment Variables > Defaults. Connection details can be specified using a standard Redis URI or individual parameters.

Command Line Arguments

When invoking directly via CLI:

Connection via URI

uvx --from redis-mcp-server@latest redis-mcp-server \n --url redis://user:pass@host:6379/0

SSL Configuration Example

uvx --from redis-mcp-server@latest redis-mcp-server \n --url rediss://user:pass@redis.example.com:6379/0

Cluster Activation

uvx --from redis-mcp-server@latest redis-mcp-server --cluster-mode

Option	Purpose	Default	Options
`--url`	Full connection string	N/A	URI format
`--host`	Target database host	`127.0.0.1`	Hostname/IP
`--ssl`	Enable secure transport	`False`	Boolean
`--cluster-mode`	Activate cluster awareness	`False`	Boolean

Environment Variables

Configuration via environment variables offers persistence across sessions.

Variable Name	Scope	Default
`REDIS_HOST`	Network Address	`"127.0.0.1"`
`REDIS_PORT`	Network Port	`6379`
`REDIS_PWD`	Authentication Secret	`""`
`REDIS_SSL`	Security Layer	`False`

Logging Control

Verbosity is managed via the MCP_REDIS_LOG_LEVEL environment variable. Standard Python logging levels (DEBUG, INFO, WARNING, etc.) are accepted. Default logging output is filtered at WARNING.

Framework Integration Examples

OpenAI Agents SDK

Install the necessary library:

commandline pip install openai-agents

Set your API key and execute the provided example script:

commandline export OPENAI_API_KEY="" python3.13 ./examples/redis_assistant.py

VS Code with Copilot

Ensure Agent Mode is active ("chat.agent.enabled": true in settings.json). Configure the server definition in mcp.json using uvx for external execution or uv run for local development execution.

Example for local development in mcp.json:

"servers": { "redis": { "type": "stdio", "command": "", "args": [ "--directory", "", "run", "src/main.py" ], "env": { "REDIS_HOST": "", "REDIS_PWD": "", } } }

Quality Assurance

Diagnostic checks on the server behavior can be performed using the official MCP Inspector tool for visualization:

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

Use Case Scenarios

Intelligent Data Agents: Empowering LLMs with direct, structured access to persistent storage.
Contextual Applications: Managing dynamic state for chatbots and user interaction flows.
Real-time Analytics: Facilitating rapid queries against Redis datasets.
Asynchronous Data Pipelines: Orchestrating event flow using Redis Streams capabilities.

License and Support

Distributed under the MIT License. For assistance or feature requests, utilize the GitHub Issues tracker.

WIKIPEDIA NOTE: XMLHttpRequest (XHR) defines a JavaScript interface for fetching resources from a server asynchronously after the initial page load, forming the basis of AJAX interactions.