Redis MCP Server Cursor IDE Setup 2026: uvx Config for Keys, Vectors & Cluster

How do you set up the Redis MCP server in Cursor? Add a redis-mcp-server entry under mcpServers in ~/.cursor/mcp.json that runs uvx --from redis-mcp-server@latest redis-mcp-server with a --url argument pointing at your Redis instance. Restart Cursor, confirm a green status, then ask it to read or write a key. No separate install step — uvx fetches and runs the package on demand from PyPI.

This guide covers Redis's own official server, maintained at redis/mcp-redis — not the older community GongRzhe/REDIS-MCP-Server implementation, which uses a different tool naming scheme and predates Redis's own release. If a config you're copying references a package other than redis-mcp-server, check which one it actually is before assuming the two are interchangeable.

Prerequisites

Step 1: Confirm Your Redis Connection String

Before touching mcp.json, confirm you can actually reach Redis. If you have redis-cli installed:

redis-cli -u redis://localhost:6379/0 ping

A PONG response means the connection details are good — put the same URL into the MCP config next. If this fails, fix the connection at the Redis level first; the MCP server can't do anything a plain client can't.

Step 2: Add the Server to Cursor's mcp.json

Recommended path — uvx, no local install step:

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

If uvx isn't on Cursor's PATH (common on macOS when uv was installed via a shell profile Cursor's background process doesn't load), use the absolute path instead — find it with which uvx and substitute that for "command": "uvx".

Alternative path — pip install, if your environment already standardizes on pip over uv:

pip install redis-mcp-server

{
  "mcpServers": {
    "redis-mcp-server": {
      "command": "redis-mcp-server",
      "args": ["--url", "redis://localhost:6379/0"]
    }
  }
}

Restart Cursor completely after editing the file.

Step 3: Authentication and TLS

For password-protected Redis, either put credentials in the URL or use discrete flags — both work, pick whichever is easier to keep out of version control:

{
  "mcpServers": {
    "redis-mcp-server": {
      "command": "uvx",
      "args": [
        "--from", "redis-mcp-server@latest",
        "redis-mcp-server",
        "--url", "rediss://your-redis-host:6380/0"
      ],
      "env": {
        "REDIS_PWD": "your-password-here"
      }
    }
  }
}

Note the rediss:// scheme (double s) for TLS, versus plain redis:// — using the wrong one against an endpoint that only accepts the other fails at the connection layer with an error that reads like a credentials problem but isn't one. Cloud providers that terminate TLS at the edge, including most managed Redis offerings, expect rediss://.

For Azure Managed Redis with Entra ID instead of a static password, the server supports auth-flow env vars rather than a password at all:

{
  "env": {
    "REDIS_ENTRAID_AUTH_FLOW": "default_credential",
    "REDIS_ENTRAID_SCOPES": "https://redis.azure.com/.default"
  }
}

default_credential walks Azure's standard credential chain (environment, managed identity, CLI login) automatically; service_principal and managed_identity are the other supported flow values if you need one specifically.

Step 4: Test the Connection

In Cursor chat:

Set a key called test:hello to the value "world" in Redis, then read it back to confirm.

A round-trip write-then-read confirms both directions work, not just that the server started. If Cursor reports a connection error rather than a Redis-level error, that points at Step 1's connection string, not the MCP config itself.

Step 5: Practical Workflows

Debugging a cache miss

Check whether the key user:1842:profile exists in Redis, what its TTL is, and what type it is. If it's expired or missing, tell me — don't guess.

Inspecting a production incident without opening redis-cli

List the 20 largest keys by memory in this Redis instance and tell me which key patterns are consuming the most space.

Working with vector data

Search the product-embeddings index for the 5 nearest vectors to this query embedding, and return the associated product IDs and scores.

Cluster health check

Report the cluster mode status and node health for this Redis instance — is anything in a degraded or failed state?

Troubleshooting

"uvx: command not found" even though uv is installed
Cursor's background process doesn't always inherit your shell's PATH, especially if uv was added via a profile script (.zshrc, .bash_profile) that only loads for interactive shells. Run which uvx in a fresh terminal and hardcode the absolute path as the command value instead of relying on PATH resolution.

Connection refused, but redis-cli connects fine from the terminal
Confirm the URL in mcp.json matches exactly what worked in Step 1 — a typo'd port, a redis:// where the instance actually needs rediss://, or a localhost reference when Cursor and Redis are actually on different machines (or different Docker networks) are the three most common mismatches.

Server connects but every command times out
Check whether a firewall or security group allows the specific host running Cursor, not just "your office network." Managed Redis instances on cloud providers often default to a narrow allowlist that a laptop on a different network won't be in.

Auth error with Entra ID that doesn't happen with az login
default_credential uses Azure's standard credential chain, but that chain behaves differently depending on what's cached on the machine. If az login works in a terminal but the MCP server still fails, the background process Cursor launches may not share that session — try service_principal with explicit CLIENT_ID, CLIENT_SECRET, and TENANT_ID env vars for a setup that doesn't depend on an interactive login being cached.

Vector search tools don't appear in the tool list
Vector search tools require RediSearch (or the equivalent module) to be loaded on the target instance. A vanilla open-source Redis without that module enabled won't expose those tools even though the MCP server itself is running fine — check your Redis instance's module list, not the MCP config.

Server works locally but not after switching to a cloud Redis provider
Re-run Step 1's redis-cli ping test against the new URL before touching mcp.json again — cloud Redis providers frequently require rediss:// (TLS) where local development used plain redis://, and that's the single most common thing that breaks in this exact migration.

When Not to Use This

Be cautious about pointing this at a production cache or session store where an agent-issued FLUSHALL or a mistaken DEL on the wrong key pattern would be a real incident. Use a read-focused workflow against production, and reserve write operations for staging or a dedicated development instance.

Frequently Asked Questions

Q: Do I need Docker to run the Redis MCP server?
A: No — uvx runs the package directly without a container. Docker is one of several supported install paths (there's an official mcp/redis image), useful if your team standardizes deployment through containers, but it isn't required for a local Cursor setup.

Q: What's the difference between redis:// and rediss:// in the connection URL?
A: The extra s means TLS. Most cloud-managed Redis instances (Redis Cloud, Azure Managed Redis, AWS ElastiCache with encryption in transit) require rediss://; local development Redis typically uses plain redis://. Using the wrong scheme fails at the connection layer.

Q: Can this connect to a Redis Cluster, not just a single instance?
A: Yes, via --cluster-mode and the relevant connection flags. Cluster topology discovery happens through the same URL or host/port configuration — point it at any cluster node and it discovers the rest.

Q: Is this the same as the Redis Cloud API MCP server?
A: No, and they solve different problems. This guide's redis-mcp-server talks to the data inside a Redis instance — keys, values, vectors. Redis's separate mcp-redis-cloud server manages Redis Cloud account resources (creating databases, checking subscription status) through Redis Cloud's control-plane API instead.

Q: How do I stop the agent from running destructive commands like FLUSHALL?
A: Cursor's tool-approval prompts cover this at the workflow level — keep manual confirmation on for write-capable tools rather than auto-approving everything. Beyond that, the cleanest boundary is a Redis ACL user with read-only permissions dedicated to the MCP connection, so a destructive command fails at the Redis level even if it's somehow issued.

Related Guides

Official docs cited