Explore and diagnose a Redis instance from Claude Code, Cursor, or any MCP client - SCAN-based key exploration, health snapshots, slowlog, and a DBA advisor, read-only by default.
@yawlabs/redis-mcp lets an agent explore and diagnose a Redis instance from Claude Code, Cursor, and any MCP client. It is 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, MIT licensed, published on npm.
npx -y @yawlabs/redis-mcp@latestGitHub · npm · Add to Yaw MCP
Anyone who has an instance they need to understand rather than administer. This server is a read-first explorer and diagnostician, not a general Redis admin console - the goal is the safe, common 90%: what is in this instance, is it healthy, and what should I worry about? Those are exactly the questions an agent should be able to answer against a production Redis without risk:
redis_scan enumerates keys with a cursor, an optional glob match and a value-type filter, and the cursor is resumable so a large keyspace pages instead of arriving all at once.redis_health rolls up INFO, DBSIZE and recent SLOWLOG into memory pressure, eviction policy, hit rate, ops/sec, persistence status, replication role, and per-database key counts. One call, not six.redis_advisor is the lint pass: big keys, missing TTLs, eviction pressure including the dangerous noeviction plus no-TTL combination, and fork-latency risk. Each finding carries a severity and an actionable fix.redis_key_info reads type, TTL, encoding, memory footprint and idle time without pulling the value at all. It is the big-key and missing-TTL probe.redis_slowlog returns recent slow-log entries with command, microseconds, timestamp and client.It deliberately does not expose EVAL, FUNCTION or SCRIPT, pub/sub, MONITOR, cluster management, or replication control. For those, use redis-cli directly. It works against Redis and Valkey; a few redis_health fields depend on the running server exposing them in INFO, and a missing field surfaces as null rather than erroring.
1. Create .mcp.json in your project root. On macOS, Linux and WSL:
{
"mcpServers": {
"redis": {
"command": "npx",
"args": ["-y", "@yawlabs/redis-mcp@latest"],
"env": {
"REDIS_URL": "redis://:password@host:6379/0"
}
}
}
}On Windows, wrap the call in cmd /c: since Node 20, child_process.spawn cannot directly execute .cmd files, and that is what npx is on Windows.
{
"mcpServers": {
"redis": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@yawlabs/redis-mcp@latest"],
"env": {
"REDIS_URL": "redis://:password@host:6379/0"
}
}
}
}Put REDIS_URL directly in the env block rather than relying on your shell profile. On Windows especially, env vars set in bash or PowerShell profiles are not inherited by MCP servers launched via cmd - the symptom is a REDIS_URL is not set error. If the instance requires a password and the URL has none you will see NOAUTH Authentication required; note the leading colon in redis://:yourpassword@host:6379, since the username is empty for the default user.
2. Restart and approve. Restart Claude Code (or your MCP client) and approve the redis MCP server when prompted. The first command is slower than the rest because the client connects lazily; later commands reuse the connection.
3. Optionally enable writes. Read-only is the default. To let the agent run mutating commands such as SET, DEL, EXPIRE and HSET through redis_command, add ALLOW_WRITES=1:
"env": {
"REDIS_URL": "redis://...",
"ALLOW_WRITES": "1"
}Prefer scoping that to dev and test instances. Even with writes on, arbitrary-execution commands stay blocked.
Running Yaw MCP? One click adds it to your local config, and it is then available in every Yaw Terminal session.
| Tool | What it does |
|---|---|
redis_scan | Enumerate keys with cursor-based SCAN, never KEYS. Optional glob match, value-type filter and resumable cursor, capped at REDIS_MAX_KEYS. |
redis_key_info | Inspect one key without reading its value: type, TTL in seconds and milliseconds, encoding, memory footprint, idle time. The big-key and missing-TTL probe. |
redis_get | Read a key's value, dispatching by type (string, hash, list, set, zset, stream). Collection reads are windowed by limit. Always read-only. |
redis_command | Run a single Redis command through the safety gate. Reads always run, writes need ALLOW_WRITES=1, and KEYS plus arbitrary-execution commands are blocked. The escape hatch for commands without a dedicated tool. |
redis_health | One-call health snapshot from INFO, DBSIZE and SLOWLOG: memory pressure, eviction policy, hit rate, ops/sec, persistence, replication role, per-db key counts, recent slow commands. |
redis_slowlog | Recent entries from the Redis slow log: command, microseconds, timestamp, client. Read-only. |
redis_advisor | Rolled-up health lints in one call: big keys, missing TTLs, eviction pressure, fork-latency risk. Each finding has a severity and a fix, and keys are SCAN-sampled so it is safe on large instances. |
Reads are type-aware without surprises: redis_get dispatches by value type and windows collection reads to a cap, so a million-element list cannot blow out the model's context. The package ships as a single bundled file with zero runtime dependencies, which is what keeps an npx cold start from turning into a multi-minute node_modules install.
SCAN, not KEYS - the load-bearing choice. Redis is single-threaded, and 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, which is a denial of service you triggered yourself. Every enumeration path here uses cursor-based SCAN or SSCAN with a bounded COUNT and a hard iteration cap, yielding the event loop between batches.ALLOW_WRITES=1, only commands on the read-only allowlist run and everything else is rejected before it reaches Redis. KEYS is explicitly rejected with a nudge to redis_scan.EVAL, FUNCTION, SCRIPT, MULTI/EXEC, MONITOR, SHUTDOWN, REPLICAOF, CLUSTER and MIGRATE stay blocked in all modes, writes enabled or not. The gate is a curated allowlist, not "anything when writes are enabled".REDIS_URL, created with something like ACL SETUSER mcp on >pass ~* +@read. Redis then enforces the boundary server-side, independent of this server's gate. ALLOW_WRITES is defense-in-depth on top of that, not the boundary itself.All of these are read from the MCP server's environment, so they go in the env block of your client config:
| Variable | Purpose |
|---|---|
REDIS_URL | Required. Redis connection string, for example redis://:pass@host:6379/0, or rediss://... for TLS. |
ALLOW_WRITES | Set to 1 or true to permit curated mutating commands via redis_command. Arbitrary-execution commands stay blocked regardless. |
REDIS_COMMAND_TIMEOUT_MS | Per-command timeout. A command that runs longer is aborted so a wedged call cannot hang the agent. |
REDIS_CONNECT_TIMEOUT_MS | TCP connect timeout. Without it a dead host hangs until the OS gives up. |
REDIS_MAX_KEYS | Cap on keys returned by a single scan, and on collection elements returned by redis_get. |
REDIS_SCAN_COUNT | COUNT hint per SCAN iteration. Higher means fewer round-trips but more work per iteration. |
REDIS_TLS_REJECT_UNAUTHORIZED | Set to false to skip TLS certificate verification, for managed Redis using private-CA certs. The connection is still encrypted. |
Managed Redis (Upstash, ElastiCache, Redis Cloud and friends). Use a rediss:// URL for TLS. If the provider serves a certificate signed by a private CA that Node's trust store does not recognize - the symptoms are self signed certificate in certificate chain or 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"
}That 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.
It is a read-first explorer and diagnostician for a Redis instance, exposed as MCP tools. An agent can enumerate keys with SCAN, read a value dispatched by type, inspect a key's type, TTL, encoding and memory footprint without reading the value, pull a one-call health snapshot from INFO, DBSIZE and SLOWLOG, and run an advisor pass that flags big keys, missing TTLs, eviction pressure and fork-latency risk. It is not a general Redis admin console.
That is the design goal. Redis is single-threaded, and KEYS walks the entire keyspace in one uninterruptible operation that blocks every other client for the duration. Every key-enumeration path here uses cursor-based SCAN or SSCAN with a bounded COUNT and a hard iteration cap, which yields the event loop between batches, and the advisor samples keys the same way. KEYS is explicitly rejected by the command gate with a nudge to redis_scan.
Not unless you opt in. Without ALLOW_WRITES=1 only commands on the read-only allowlist run, and everything else is rejected before it reaches Redis. Setting ALLOW_WRITES=1 additionally permits a curated set of mutating commands through redis_command. Arbitrary-execution commands such as EVAL, FUNCTION, SCRIPT, MULTI, MONITOR, SHUTDOWN, REPLICAOF, CLUSTER and MIGRATE stay blocked in all modes, and the gate is fail-closed: a command on neither allowlist is rejected.
No. The cleanest posture is a least-privileged Redis user in REDIS_URL, created with something like ACL SETUSER mcp on >pass ~* +@read. Redis then enforces the boundary server-side, independent of this server's own gate. ALLOW_WRITES is defense-in-depth on top of that, not a replacement for it.
Use a rediss:// URL for TLS. If the provider serves a certificate signed by a private CA that Node's trust store does not recognize, the symptoms are errors like self signed certificate in certificate chain or unable to verify the first certificate; setting REDIS_TLS_REJECT_UNAUTHORIZED=false disables certificate-chain verification only, and the connection is still TLS-encrypted end to end. Where you can install the CA, prefer NODE_EXTRA_CA_CERTS over disabling verification.
Published by Yaw Labs.