@yawlabs/redis-mcp

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:

Connecting to managed Redis (Upstash, ElastiCache, Redis Cloud, etc.)

Use a rediss:// URL for TLS. If the provider serves a cert signed by a private CA that Node's trust store doesn't recognize (symptoms: self signed certificate in certificate chain, unable to verify the first certificate), add REDIS_TLS_REJECT_UNAUTHORIZED=false:

"env": {
  "REDIS_URL": "rediss://default:pass@host:6379",
  "REDIS_TLS_REJECT_UNAUTHORIZED": "false"
}

This disables certificate-chain verification only - the connection is still TLS-encrypted end-to-end. Where you can install the CA, prefer NODE_EXTRA_CA_CERTS over disabling verification.

Troubleshooting

REDIS_URL is not set - Your MCP client is launching the server without the env var. On Windows especially, env vars set in bash / PowerShell profiles are not inherited by MCP servers launched via cmd. Put REDIS_URL directly in the env block of .mcp.json.

NOAUTH Authentication required - The instance requires a password and the URL has none. Add it: redis://:yourpassword@host:6379 (note the leading colon - the username is empty for the default user).

<COMMAND> mutates state and is blocked: ALLOW_WRITES is not set - You asked for a write through redis_command in read-only mode. Add ALLOW_WRITES=1 to the env block (dev/test), or - cleaner - use a Redis ACL user scoped to the access you want.

KEYS is blocked - Intentional. Use redis_scan (cursor-based) to enumerate keys; it is safe on a large keyspace where KEYS is not.

First command is slow, subsequent commands are fast - Expected. The client connects lazily on the first command; later commands reuse the connection.

Development

npm install
npm test          # build + unit tests (no live Redis needed)

The unit suite covers the pure logic - command allowlist enforcement, SCAN cursor paging, INFO/SLOWLOG parsing, and the advisor heuristics - and runs without a Redis instance. Integration tests that exercise live paths (npm run test:integration) require a disposable Redis at REDIS_URL.

License

MIT © 2026 YawLabs