Redis MCP: Connect Your AI Agent to Your Database

Redis MCP lets an AI client call tools that read and change data in your Redis database. To connect your own database, run the official redis-mcp-server, give it a Redis address and a restricted credential, then register that process in Cursor or Claude Desktop.

This guide gets that connection working with two small demo keys. You will read a string and a hash, inspect a TTL, and check that Redis rejects a write. You can start on your computer, then use the same approach with a dedicated Managed Redis instance in Lizard (lizard.build).

Tested September 27, 2026, Dubai time: Python 3.12.10, Redis 8.8.0, redis-mcp-server 0.5.1, MCP Python SDK 1.30.0 and redis-py 8.1.0. The downloadable test passed 14 checks against an isolated local Redis process through MCP over stdio. It did not test a hosted database, TLS or the Cursor and Claude Desktop interfaces. Those setup steps follow the linked product documentation. This guide was prepared with AI assistance; the test script and results are available below.

Choose the Redis MCP server that accesses data

The official Redis MCP server connects to a Redis endpoint. Its tools include string and hash reads, writes, key inspection and server information. Redis enforces the permissions of the credential you supply.

There are several Redis tools with MCP in their names:

Tool	What it connects to	Use it for
redis/mcp-redis, packaged as redis-mcp-server	Your Redis database	Reading or changing application data
Redis documentation MCP at redis.io/mcp	Redis documentation	Looking up commands and examples
Redis Cloud MCP	The Redis Cloud management API	Managing Redis Cloud resources

We use the first one. A documentation connection will not give your agent access to your keys. Redis describes the distinction in its agent setup guide.

The MCP process runs on the same computer as your client and communicates through standard input and output, or stdio. It opens a separate network connection to Redis. This setup needs no public HTTP endpoint for MCP. A green connection indicator in the client only shows that the MCP process started; a tool call must still prove that Redis authentication and data access work.

1. Prepare a small Redis database

Use a dedicated learning instance with synthetic data. You need Python 3.10 or later, uv, and access to a Redis server. The local route also needs redis-server on your PATH.

Download these files into a new demo directory:

• requirements.txt: the pinned Python packages.
• setup.py: creates two keys and a restricted reader, then writes the MCP configuration.
• verify.py: starts its own local Redis process and tests the MCP connection.
• validation.json: the results from this guide's test run.

On macOS or Linux, create the Python environment:

uv venv .venv --python 3.12
uv pip install --python .venv/bin/python -r requirements.txt

In a separate terminal, start a temporary Redis instance:

redis-server --bind 127.0.0.1 --port 6391 --save "" --appendonly no

Leave that terminal running. This local instance has no persistence and listens only on loopback. Stop it with Ctrl+C when you finish. If port 6391 already belongs to another process, pick a free port and set ADMIN_REDIS_URL to match before running setup.

In your demo directory, run:

.venv/bin/python setup.py

The setup script connects to redis://127.0.0.1:6391/0 by default. It creates:

Key	Type	Value	Initial TTL
mcpdemo:status	String	ready	3,600 seconds
mcpdemo:session:42	Hash	user=demo-user, language=english	3,600 seconds

It also creates the user mcp_reader with a random password. It refuses to replace an existing user or demo keys, so a repeat run on the same instance stops with an explanation.

The script saves mcp.local.json with an absolute path to the installed MCP server. The file contains the reader password. Keep it private and add these paths to the demo project's .gitignore before committing anything:

.venv/
.env
mcp.local.json
.cursor/mcp.json
test-runs/

On Windows, use .venv\Scripts\python.exe for the Python commands. The script chooses the matching executable path for the generated config. This guide's automated run used macOS.

2. Understand the reader's permissions

The script applies this Redis ACL policy. This is Redis command syntax, with a placeholder password; the setup script generates the real password for you:

ACL SETUSER mcp_reader reset on >REPLACE_WITH_RANDOM_PASSWORD ~mcpdemo:* -@all +ping +get +hget +hgetall +type +ttl

The rules permit reads of known strings and hashes under mcpdemo:*, plus type and TTL checks. They deny writes, administration commands, pub/sub and key enumeration. The Redis ACL reference explains each rule.

A read-only prompt does not enforce read-only access. The database credential does. The MCP server can still advertise write tools; Redis should reject their execution for this user. Keep the client's approval prompts enabled as another check on which calls run.

Why the policy does not allow SCAN

An ACL key pattern restricts access to key values. It does not make SCAN return only the key names under that pattern. In our test, granting +scan let mcp_reader discover the name private:sentinel, even though it could not read that key's value. Revoking SCAN blocked enumeration again.

Start with known demo keys. If you later allow browsing on a separate instance that holds no unrelated data, use scan_keys in small iterations and follow the returned cursor until it becomes zero. COUNT is a work hint, not a hard result limit. See the SCAN reference. The tutorial's default policy deliberately rejects both scan_keys and scan_all_keys.

3. Add Redis MCP to Cursor or Claude Desktop

Open the generated mcp.local.json locally. It has this shape:

{
  "mcpServers": {
    "redis-demo": {
      "command": "/ABSOLUTE/PATH/redis-mcp-demo/.venv/bin/redis-mcp-server",
      "args": ["--host", "127.0.0.1", "--port", "6391", "--db", "0"],
      "env": {
        "REDIS_USERNAME": "mcp_reader",
        "REDIS_PWD": "YOUR_GENERATED_READER_PASSWORD"
      }
    }
  }
}

Use the actual generated file, not the placeholders above. Merge the redis-demo entry into your client's existing mcpServers object; keep any other servers already there.

Cursor: use .cursor/mcp.json in the demo project, or ~/.cursor/mcp.json for a user-level setup. Check the server in the client's MCP settings and enable it for the project. Cursor documents the file locations in its MCP integration guide.

Claude Desktop: merge the entry into claude_desktop_config.json. On macOS that file lives under ~/Library/Application Support/Claude/. Restart the app after saving. Follow the Redis client configuration guide for the current client steps.

This guide passes host, port and database as explicit arguments. In the tested 0.5.1 command-line entry point, default CLI values overwrite those settings if you supply only environment variables. Supplying REDIS_HOST alone can therefore leave the process trying 127.0.0.1. The username and password in the configuration above use the supported REDIS_USERNAME and REDIS_PWD variables.

4. Prove that the connection works

Ask your client to use the Redis tools explicitly. Approve the requested reads and inspect the tool output before relying on the model's summary.

Use redis-demo to get mcpdemo:status. Then use hgetall on
mcpdemo:session:42 and type on that same key. Report the raw
tool results and the remaining TTL. Do not change any data.

The expected results are:

• get returns ready.
• hgetall returns the two synthetic fields.
• type returns hash and a positive TTL below 3,600 seconds.

The official type tool includes TTL in its response. In our run it returned:

{
  "key": "mcpdemo:session:42",
  "type": "hash",
  "ttl": 3591
}

Your number will differ. A TTL of -2 means the key does not exist; -1 means it exists without expiry. If more than an hour has passed, the demo data may have expired. An authorised administrator can reseed the keys, or you can start a fresh local instance and run setup again.

Next, use the disposable demo to check the restriction:

Use redis-demo to try setting mcpdemo:status to changed once.
Report the exact tool result. Then read mcpdemo:status again.
Do not retry with other tools or credentials.

Our MCP call returned User mcp_reader has no permissions to run the 'set' command, and a separate read still returned ready. This verifies both the denial and the unchanged value. Some Redis MCP tools return an error as text, so inspect the response content even when the MCP call itself completes.

You can reproduce the underlying protocol checks without a model API key:

.venv/bin/python verify.py

The script starts its own Redis process on a free loopback port. It does not accept your database URL. It checks authentication, MCP startup, advertised tools, reads, TTL, blocked writes, unchanged data, another key prefix, missing keys, and the SCAN behaviour above. It stops only the process it created and saves validation.json beside the script.

5. Connect a dedicated Managed Redis instance

For a shared application database, create Managed Redis in the project dashboard and follow the connection guide. Use a separate learning instance for this exercise. Copy its connection URL into a private local .env file under the name ADMIN_REDIS_URL; never paste that administrator credential into an AI chat.

Load your own trusted file and run setup from the demo directory:

set -a
. ./.env
set +a
.venv/bin/python setup.py
unset ADMIN_REDIS_URL

The setup script uses that credential to create the synthetic keys and reader. Its generated MCP configuration contains only the new reader credential. It extracts host, port and database from the URL, and enables TLS certificate verification for rediss:// endpoints. Query parameters and custom certificate paths need a separate configuration; the script stops rather than guessing them.

The endpoint must be reachable from the computer running MCP. A plain redis:// URL has no transport encryption. Use a trusted private route or a verified TLS endpoint where available; changing the URL prefix does not add TLS support to a server. The current Managed Redis guide shows redis:// connections, so do not assume it supplies a public TLS endpoint.

Creating an ACL user also requires the provider to permit ACL SETUSER. If the provider denies it, use its supported user-management controls before connecting the agent. Do not put the administrator password into the MCP config as a workaround.

Redis ACL changes made at runtime need a persistence mechanism to survive a Redis restart. The current Managed Redis startup configuration does not declare an ACL file, so treat this demo user as temporary and verify it after restarts. Do not assume AOF persistence saves ACL users. Keep the tested permissions in your setup process and review the storage and recovery guide for the service's other limits.

Fix common Redis MCP connection errors

Symptom	Check
MCP process fails to start	Use the absolute executable path from the generated config. Confirm that the Python environment still exists.
Connection refused or timeout	Check the explicit --host and --port, Redis availability and network access from the MCP computer.
WRONGPASS or authentication failed	Check REDIS_USERNAME and REDIS_PWD. A password for default does not authenticate mcp_reader. Check whether a restart removed the temporary ACL user.
NOPERM or a permission error	Compare the requested command and key with the ACL. A denied write, SCAN or unrelated prefix is expected in this guide.
WRONGTYPE	Use type first. Read strings with get; read hashes with hgetall.
Missing key or TTL -2	Check the database number, exact key name and expiry.
TLS certificate failure	Confirm the server actually supports TLS and supply its trusted CA through the server's documented SSL options. Keep certificate checks enabled.
JSON.GET or FT.SEARCH is unknown	Those tools need the matching Redis JSON or search capabilities. Core string/hash tools working does not prove those capabilities exist.

What to build after the connection works

Use this setup to inspect a synthetic session, check a cache entry's lifetime or debug an agent's saved context. Tool results can enter your model conversation, so choose which data the agent may read before you connect a real application.

If you want the application to save memories automatically, continue with AI agent memory with Redis. If your agent needs relational data, use the separate reader role in Postgres MCP.

Start with Managed Redis, connect the restricted reader, and verify one successful read and one denied write before expanding the tool set.