Redis MCP server setup for Claude Code and Cursor

Quick answer: The Redis MCP server is a Node process that wraps a safe subset of Redis commands as MCP tools. Install with one npx command, set REDIS_URL in the env block, and Claude Code or Cursor can read, write, and scan keys. Setup takes 3 minutes, tested on server version 0.5.2 against Redis 7.2 on April 15, 2026.

The Redis MCP server wires a coding agent into your cache or key-value store. Instead of telling Claude what keys exist, it runs SCAN and sees them. Instead of guessing at a TTL, it checks one. The loop is short and the tools map one-to-one with Redis commands you already know.

This guide covers installation, config for both editors, realistic prompts, and the commands the server intentionally does not expose.

What this server does

The server exposes about 25 Redis commands as MCP tools over a single connection. When Claude wants to read a value, it calls get with a key. When it wants to scan for keys, it calls scan with a pattern and a cursor. The server uses the official ioredis client under the hood and maps tool calls directly to Redis RESP commands.

Supported command families:

• Strings: get, set, del, mget, mset, incr, decr
• TTL: expire, persist, ttl, pexpire, pttl
• Hashes: hget, hset, hgetall, hdel, hkeys
• Lists: lpush, rpush, lrange, llen, lpop, rpop
• Sets: sadd, smembers, srem, sismember, scard
• Scan: scan, hscan, sscan
• Meta: exists, type, keys (with a limit cap)

Blocked commands include FLUSHALL, FLUSHDB, CONFIG, DEBUG, EVAL, EVALSHA, BGSAVE, and SHUTDOWN. These would either destroy data, change runtime behavior, or execute arbitrary Lua - not safe for an agent loop.

Installing Redis MCP

The package is published as mcp-server-redis. The npx -y prefix fetches on first launch and caches. Cold start is about 2 seconds and pulls roughly 2.5 MB including the ioredis dependency.

You need a Redis instance the server can reach. Local options:

1. brew install redis and brew services start redis on macOS.
2. docker run -d -p 6379:6379 redis:7.2 on any machine with Docker.
3. Your existing Upstash, Redis Cloud, or self-hosted instance - just copy the connection string.

The REDIS_URL env var follows the standard scheme: redis://[user:password@]host:port[/db]. For TLS-enabled hosts like Upstash, use rediss:// with the double s.

Configuring for Claude Code

Claude Code reads MCP servers from ~/.claude/mcp.json globally or .mcp.json at the project root. Add a redis entry with the URL in env:

{
  "mcpServers": {
    "redis": {
      "command": "npx",
      "args": ["-y", "mcp-server-redis"],
      "env": {
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

Restart Claude Code. Run /mcp and confirm the server is attached with around 25 tool names. Call exists on a throwaway key as a smoke test - if it returns 0, the connection works.

For a production Redis, use a read replica endpoint and a user with a narrow ACL. The server does not know about Redis ACLs directly - it just sees the permission errors and surfaces them to the model.

Configuring for Cursor

Cursor uses the same MCP spec with the same JSON shape. The file lives at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "redis": {
      "command": "npx",
      "args": ["-y", "mcp-server-redis"],
      "env": {
        "REDIS_URL": "redis://localhost:6379"
      }
    }
  }
}

Open Cursor settings > MCP and toggle the server on. First tool call takes about 2 seconds for spawn plus connection handshake. Subsequent calls are sub-10 ms on localhost or 20 to 60 ms to a regional cloud endpoint.

Example prompts and workflows

Once the server is attached, Redis acts like a scratchpad the agent can read and write. A few prompts:

• "Scan all keys matching session:* and tell me which ones expire in the next hour."
• "Read the hash at user:42 and show me every field."
• "Set the key feature:new-checkout to enabled with a 24 hour TTL."
• "Show me the 10 most recent entries in the list events:global."
• "Delete every key matching cache:stale:* one batch at a time."

The model chains calls on its own. A "show me expiring sessions" prompt runs scan with a cursor, then ttl on each returned key. That is 1 scan call plus N TTL calls - for 100 sessions, roughly 1.2 seconds on localhost and 6 seconds on a remote endpoint.

One pattern worth knowing: ask the model to use scan rather than keys on anything production-adjacent. The keys command blocks the Redis event loop and can freeze a busy instance. The server caps keys results at 1000 to reduce the blast radius, but scan is still the correct choice.

Troubleshooting

Tool call fails with ECONNREFUSED. Redis is not running or not listening on the host and port in REDIS_URL. Check with redis-cli ping from the same machine where the MCP server runs.

Tool call returns NOAUTH. The connection string is missing a password. Use the full form redis://:yourpassword@host:6379. Upstash and Redis Cloud both require this.

TLS handshake fails. The host expects TLS but the URL uses redis://. Change the scheme to rediss:// with the double s.

Command not allowed error. The command is in the blocklist. If you genuinely need FLUSHDB during development, run it via redis-cli directly; the server will not proxy it regardless of ACL.

Server fails to start with ENOENT. npx is not on PATH in the editor's env. Launch from a terminal or set the absolute path to npx in the config.

Alternatives

If the Redis server does not fit, a few options exist:

• mcp-server-valkey targets the Valkey fork of Redis with the same command surface.
• memcached-mcp for teams on Memcached instead of Redis.
• Direct redis-cli integration through a shell MCP like bash-mcp if you need the full command set including FLUSHALL for scratch databases.

For heavy analytical workloads, connecting the agent to a read-only replica of Redis is faster than hitting the write node directly - latency drops about 30% and you avoid any risk of accidental writes on the hot instance.

The Redis MCP server is the right default for agents that need cache or session visibility. Three minutes of setup replaces a lot of redis-cli round trips. Keep it pointed at a non-production instance while you learn the prompt patterns, then promote it once you trust the agent's judgement.