@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.

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):