The official Redis MCP server (mcp-redis) lets Claude Code read, write, and query Redis using natural language, no custom tooling required. Point it at any Redis instance (local, Docker, cloud, or private VPC), and Claude Code gains access to strings, hashes, JSON, lists, sets, sorted sets, streams, and vector search. Setup takes under five minutes for a single developer. The harder problem, and the one most guides skip, is making this safe and observable when a team of engineers connects AI coding tools to staging or production Redis.
This article covers the fast path for individual setup, then goes deep on the credential management, network access, permission scoping, and audit patterns that matter once Redis MCP moves beyond a single laptop.
What Redis MCP actually exposes
The mcp-redis server publishes tools that map to Redis data operations and server management commands. Through MCP, Claude Code can:
- Read and write keys across all core data types (strings, hashes, lists, sets, sorted sets, JSON, streams)
- Perform vector similarity search over Redis-indexed embeddings
- Run server health checks (
DBSIZE,INFO,PING) - Manage stream consumer groups
This is the data-plane MCP server. Redis also publishes mcp-redis-cloud, a separate server for managing Redis Cloud subscriptions (creating databases, checking metrics, managing backups). The two serve different purposes. If you want Claude Code to query or modify data in a Redis instance, you want mcp-redis. If you want to manage your Redis Cloud account, you want mcp-redis-cloud. Most developers searching for Claude Code Redis MCP setup are after the data-plane server.
Single-developer setup for Claude Code
Prerequisites
- A running Redis instance (local, Docker, or remote)
- Claude Code installed
- Node.js or Docker available for running the MCP server
Option 1: Claude Code CLI (fastest)
claude mcp add redis -- npx -y @redis/mcp-redis@latest \
--redis-url redis://localhost:6379
Verify:
claude mcp list
Option 2: JSON configuration
Edit ~/.claude/settings.json (or your project-level .mcp.json):
{
"mcpServers": {
"redis": {
"command": "npx",
"args": [
"-y",
"@redis/mcp-redis@latest",
"--redis-url",
"redis://localhost:6379"
]
}
}
}
Option 3: Docker
docker run -i --rm \
-e REDIS_URL="redis://host.docker.internal:6379" \
mcp/redis
Once connected, try a prompt like "How many keys does my database have?" or "Show me all keys matching user:*" to confirm the MCP server is working.
Setup for Cursor, Codex, and other MCP clients
The same MCP server works with Cursor, Codex, VS Code with Copilot, and Gemini CLI. The difference is where the configuration lives:
- Claude Code: ~/.claude/settings.json or project .mcp.json
- Cursor: Cursor Settings → Features → MCP → mcp.json
- VS Code / Copilot: .vscode/mcp.json in the workspace
- Codex: ~/.codex/config.toml in the MCP server section
The command and args are identical across clients. If your team uses multiple editors, you will end up duplicating the Redis connection string, including credentials, into each config file. This becomes a problem at team scale, which is covered below.
Connecting to private or remote Redis
A local redis://localhost:6379 connection is fine for experimentation. Production and staging Redis instances are typically inside a VPC, behind a firewall, or require TLS with mutual authentication.
Redis Cloud or Upstash (public endpoint)
Managed Redis services expose a public TLS endpoint. Pass the full connection string:
--redis-url rediss://default:YOUR_PASSWORD@your-host.redis.cloud:6380
The rediss:// scheme enables TLS. The password is embedded in the URL, which means it ends up in your MCP config file in plaintext.
Private VPC Redis
If your Redis instance is only reachable from within a private network, the MCP server running on your laptop cannot connect directly. Common solutions:
- SSH tunnel: Forward a local port to the remote Redis through a bastion host. Point the MCP server at
redis://localhost:<forwarded-port>. - VPN: Connect your development machine to the VPC. The MCP server connects to the private IP directly.
- Tailscale or similar overlay network: Add the Redis host and your development machine to the same network. No port forwarding, no public exposure. The MCP server connects to the Redis host's private address as if it were local.
The network access pattern you choose determines who can reach Redis and how you audit that access, which leads directly to the governance problem.
Governing AI in enterprise settings
Every Redis MCP setup guide shows a single developer configuring a connection string on their machine. That works until you have 10 or 50 engineers, each needing access to Redis through Claude Code, Cursor, or Codex. At that point, several problems compound.
Credential distribution
The Redis connection URL contains the password. Sharing it through project-scoped .mcp.json files means every developer (and every tool on their machine) holds the production credential. When someone leaves the team, you rotate the password and update every config file across every machine.
No user attribution
Redis sees one authenticated client, the MCP server. Whether Alice or Bob issued the DEL command through Claude Code, the Redis slow log shows the same connection. You have no audit trail mapping destructive operations to individual engineers.
No command restriction
The mcp-redis server exposes read and write tools. There is no built-in mechanism to:
- Restrict a developer to read-only access
- Limit operations to specific key patterns
- Block commands like
FLUSHDB
The model decides which tools to call based on the user's prompt, and the MCP server executes them.
No environment boundaries
Without explicit separation, a developer who connects Claude Code to staging Redis can just as easily connect to production by changing the URL. There is no policy layer enforcing which environments a given user or device is allowed to reach.
Safe access patterns for production Redis
Separate MCP server instances per environment
Run distinct MCP server configurations for dev, staging, and production. Use different Redis credentials for each, and distribute only the credentials appropriate to each developer's role. This is the minimum viable separation, but it still relies on each developer configuring their own machine correctly.
Read-only Redis users
Redis 6+ ACLs let you create users with restricted command sets:
ACL SETUSER readonly on >password ~* +get +mget +hgetall +lrange +smembers +zrange +ft.search -@write -@admin
Point the MCP server at this read-only user for investigation and debugging workflows. Reserve write-capable credentials for specific, approved use cases.
Key pattern scoping
Redis ACLs also support key pattern restrictions:
ACL SETUSER staging-reader on >password ~staging:* +@read
This limits the user to keys matching staging:*, preventing accidental access to production data even if the MCP server connects to a shared Redis instance.
Centralized access through an AI gateway
For organizations already running Tailscale, Aperture by Tailscale offers a different model: instead of distributing Redis credentials and provider API keys to each developer's machine, route AI traffic through a centralized gateway inside your tailnet. Aperture identifies each user by their Tailscale identity, injects provider credentials on their behalf, and captures full request and response telemetry, including MCP tool calls. This means you get per-user attribution, session-level audit logs, and centralized visibility into which engineers are using which AI tools against which backends, without modifying the MCP server itself or editing config files on every laptop.
This approach is particularly relevant when connecting Claude Code to private Redis instances. Since both the developer's machine and the Redis host are on the tailnet, there is no need for SSH tunnels, VPNs, or public endpoints. The AI gateway sits in the request path, providing the observability and credential management layer that the MCP protocol itself does not include.
Observability and audit trails
The mcp-redis server does not produce audit logs. If you need to answer "who queried production Redis through Claude Code at 3am," you need to build that visibility yourself. Options include:
- Redis slow log and
MONITORcommand: Shows commands executed, but not which human initiated them. - MCP client-side logging: Claude Code session logs capture tool invocations locally, but these are scattered across developer machines.
- Proxy-level capture: An AI gateway or MCP proxy that sits between the client and the MCP server can log every tool call with user identity, timestamp, and full payload. This is the only approach that provides centralized, attributable audit trails without modifying the MCP server.
- SIEM export: For compliance workflows, export captured logs to S3, Splunk, or your existing security tooling.
For a solo developer exploring Redis data through Claude Code or Cursor against a local or development instance, the official mcp-redis server is the right choice. It is well-maintained, covers all core Redis data types, and works with every major MCP client.