Redis MCP Server

@yawlabs/redis-mcp

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

Then give it your `REDIS_URL`. The button deliberately carries no connection string, and Yaw MCP will not prompt for one: it asks only for variables whose names look like credentials, and REDIS_URL does not. Until it is set, the server exits at startup with REDIS_URL is not set. Store it in Yaw MCP's encrypted vault in one step:

yaw-mcp set redis env.REDIS_URL --secret

The value is read from a no-echo prompt (or piped stdin), never from the command line; the vault entry is named redis_redis_url and the server's entry gets "REDIS_URL": "${secret:redis_redis_url}". Yaw MCP reads the vault when it starts the server, so after changing the value run mcp_connect_deactivate redis (or start a new session) for the new one to take effect.

Explore and diagnose a Redis instance from Claude Code, Cursor, and any MCP client. Read-only by default - writes opt in via a single env var - and key enumeration always uses SCAN, never the O(N) KEYS, so it is safe to point at a production instance with millions of keys.

Built and maintained by Yaw Labs.

Why this one?

• `SCAN`, never `KEYS`. Every key-enumeration path uses cursor-based SCAN with a bounded COUNT and an iteration cap. KEYS * is O(N) over the entire keyspace and blocks Redis's single-threaded event loop for the full scan - a self-inflicted outage on a large instance. SCAN yields between batches. See Security.
• Read-first command gate. Tools run a curated read-only command allowlist by default. Mutating commands (SET, DEL, EXPIRE, HSET, ...) require ALLOW_WRITES=1. Arbitrary-execution commands (EVAL, FUNCTION, SCRIPT, MULTI, MONITOR, SHUTDOWN, CLUSTER, ...) are never exposed, even with writes on - the gate is a curated allowlist, not "anything when writes are enabled".
• Type-aware reads without surprises. redis_get dispatches by value type (string / hash / list / set / zset / stream) and windows collection reads to a cap, so a million-element list can't blow out the model context. redis_key_info reads type / TTL / encoding / memory footprint without pulling the value at all.
• Health in one call. redis_health rolls up INFO + DBSIZE + recent SLOWLOG into memory pressure, eviction policy, hit rate, ops/sec, persistence status, replication role, per-database key counts (and how many lack a TTL), and the most recent slow commands.
• A real advisor. redis_advisor is the "what should I be looking at?" lint pass: big keys, missing TTLs, eviction pressure (including the dangerous noeviction + no-TTL combination), and fork-latency risk - each with a severity and an actionable fix. Keys are SCAN-sampled, so it is safe on a large instance.
• Instant startup. Ships as a single bundled file with zero runtime dependencies. No multi-minute node_modules install on every npx cold start.

Scope

This server is a read-first explorer and diagnostician, not a general Redis admin console. It deliberately does not expose EVAL/FUNCTION/SCRIPT, pub/sub, MONITOR, cluster management, or replication control. For those, use redis-cli directly. The goal here is the safe, common 90%: "what's in this instance, is it healthy, and what should I worry about?" - the questions an agent should be able to answer against a production Redis without risk.

Works against Redis 6+ and Valkey. A few redis_health fields (latest_fork_usec, aof_enabled) depend on the running server exposing them in INFO; missing fields surface as null rather than erroring.

Quick start

1. Create `.mcp.json` in your project root

macOS / Linux / WSL:

{

"mcpServers": { "redis": { "command": "npx", "args": ["-y", "@yawlabs/redis-mcp@latest"], "env": { "REDIS_URL": "redis://:password@host:6379/0" } } } }

Windows:

{

"mcpServers": { "redis": { "command": "cmd", "args": ["/c", "npx", "-y", "@yawlabs/redis-mcp@latest"], "env": { "REDIS_URL": "redis://:password@host:6379/0" } } } }

Why the extra step on Windows? Since Node 20, child_process.spawn cannot directly execute .cmd files (that's what npx is on Windows). Wrapping with cmd /c is the standard workaround.

2. Restart and approve

Restart Claude Code (or your MCP client) and approve the redis MCP server when prompted.

3. (Optional) Enable writes

Read-only is the default. To let the agent run mutating commands (SET, DEL, EXPIRE, HSET, ...) via redis_command, add ALLOW_WRITES=1:

"env": {

"REDIS_URL": "redis://...", "ALLOW_WRITES": "1" }

Prefer scoping this to dev/test instances. Even with writes on, arbitrary-execution commands stay blocked.

Security

`SCAN`, not `KEYS` - this is the load-bearing choice. Redis is single-threaded. KEYS pattern walks the entire keyspace in one uninterruptible operation; on an instance with millions of keys it blocks every other client for the duration - effectively a denial of service you triggered yourself. Every key-enumeration path in this server (redis_scan, the advisor's key sampling, redis_get's set reads) uses cursor-based SCAN/SSCAN with a bounded COUNT and a hard iteration cap, which yields the event loop between batches. KEYS is explicitly rejected by the command gate with a nudge to redis_scan.

Read-only by default. Without ALLOW_WRITES=1, only commands on the read-only allowlist run; everything else is rejected before it reaches Redis. With ALLOW_WRITES=1, a curated set of mutating commands is additionally permitted - but arbitrary-execution commands (EVAL, FUNCTION, SCRIPT, MULTI/EXEC, MONITOR, SHUTDOWN, REPLICAOF, CLUSTER, MIGRATE, ...) remain blocked in all modes. The gate is fail-closed: a command on neither allowlist is rejected, so a command we never anticipated can't slip through.

Use Redis ACLs as the primary control. As with a database role, the cleanest posture is a least-privileged Redis user (ACL SETUSER mcp on >pass ~* +@read) in REDIS_URL. Redis then enforces the boundary server-side, independent of this server's gate. ALLOW_WRITES is defense-in-depth on top of that.

See SECURITY.md for vulnerability reporting.

Tools

Configuration

All env vars are read from the MCP server's environment. The last three are read by the redis-mcp launcher rather than the server, so they have no effect when a host runs dist/index.js directly - and neither does the launcher's oam version check (see Runtime):

| REDIS_MCP_SANDBOX | unset | 1 or true (any case, surrounding spaces ignored) runs the server under oam's --permission sandbox: filesystem and child processes denied, network limited to the host and port in REDIS_URL (port 6379 if the URL names none). An IPv6 literal (redis://[::1]:6379) is pinned like any other host. The host and port are read the way ioredis reads them, so a scheme-less `REDIS_U