redis-guard-mcp

A Redis MCP server whose "read-only" isn't a label — it's the entire tool surface. Every tool maps to exactly one safe, read-only Redis command through redis-py's typed API. There is no "run this command string" tool to mislabel.

Why this exists

Redis is one of the most deployed pieces of infrastructure in professional backends (cache, session store, queue, rate limiter, pub/sub), and its command surface includes some of the most dangerous single commands in any widely-used data store:

• EVAL/EVALSHA/FCALL — arbitrary Lua execution inside the Redis process.
• CONFIG SET dir + CONFIG SET dbfilename + SAVE — the standard, widely-documented technique for writing an arbitrary file (e.g. a web shell into a web root, or a cron job) to disk through Redis alone.
• MODULE LOAD — loads an arbitrary shared library into the Redis process. Direct RCE if an attacker can get a .so/.dll onto disk.
• FLUSHALL/FLUSHDB — deletes every key in the database, immediately, no confirmation.
• SHUTDOWN, DEBUG, SLAVEOF/REPLICAOF, ACL, CLIENT KILL — server-crashing, replication-hijacking, permission-rewriting, and session-terminating admin surface.

A published audit of MCP servers found one where a command-execution tool was labeled readonly: true in its metadata but still accepted and ran EVAL and FLUSHALL — the metadata was decorative, not enforced. Checked directly against the official redis/mcp-redis server: its own documentation states the only mitigation for any of the above is configuring Redis ACLs yourself — the server ships with no built-in blocking of EVAL, FLUSHALL, CONFIG, MODULE, or DEBUG, and no read-only mode of its own. Safety is entirely the operator's responsibility, by default, out of the box.

How redis-guard-mcp is different

1. The allowlist isn't a filter — it's the tool surface. Nothing in this server takes an arbitrary command string. Every tool is a specific Python function that calls one specific redis-py method (r.get(key), r.hget(key, field), ...). There is no code path through which EVAL, CONFIG, MODULE, FLUSHALL, or any other command not explicitly implemented as its own tool could ever be sent — not because it's checked and rejected, but because the client code to send it simply doesn't exist here.
2. Real privilege enforcement too, not just app-level restriction. The recommended (and startup-checked) setup connects with a Redis ACL user created with +@read -@write -@admin -@dangerous. Even a bug in this server's own code couldn't run a write or admin command against a correctly-configured connection, because Redis itself would refuse it at the protocol level. Rule order matters — CLIENT KILL/PAUSE/ LIST/UNBLOCK belong to both @admin and @connection, so ... -@admin +@connection (the wrong order) silently re-grants those four commands. This is not a hypothetical: an early version of this project's own setup script had exactly that ordering, and a security review ran CLIENT PAUSE against the shipped "correctly-configured" user and it worked — a server-wide DoS primitive, from a user this project's own documentation claimed couldn't do it. Fixed by putting +@connection first; see scripts/setup_dev_redis.sh for the correct order and a comment explaining why it can't be swapped back.
3. Cursor-based, never single-shot, for every collection. KEYS is in Redis's own built-in @dangerous category because a single call can block the entire server serializing a large keyspace — the same is true of HGETALL on a large hash and SMEMBERS on a large set, just less famously. Every "give me a collection" tool here is either cursor-based (redis_scan_keys/redis_hscan/redis_sscan) or capped at 1000 items per call with an explicit truncated flag (redis_lrange/redis_zrange) — never a call that can make the server materialize an arbitrarily large collection in one shot.
4. A privilege check that asks Redis, not a re-implementation of Redis's own semantics. redis_check_permissions() uses ACL DRYRUN — Redis's own "would this command actually succeed for this user" answer — against a curated list of dangerous commands, rather than trying to re-derive the answer from parsing the ACL rule list (which is exactly how the rule-order bug above happened: a category-list read in isolation can't see that @admin and @connection overlap). would_succeed should always come back empty.

Tools

Tool	Does
redis_get(key)	Get a string value
redis_mget(keys)	Get multiple string values as {key: value} (max 200 keys)
redis_type(key)	Report a key's Redis type
redis_ttl(key)	Seconds until expiry (-1 none, -2 missing)
redis_exists(keys)	Count how many of the given keys exist (max 200 keys)
redis_scan_keys(pattern="*", cursor=0)	One SCAN page of matching keys
redis_hget(key, field)	One hash field
redis_hscan(key, cursor=0)	One HSCAN page of a hash's fields
redis_lrange(key, start=0, stop=None)	List elements, capped at 1000 per call
redis_sscan(key, cursor=0)	One SSCAN page of a set's members, sorted
redis_zrange(key, start=0, stop=None, with_scores=False)	Sorted set members, capped at 1000 per call
redis_dbsize()	Total key count
redis_check_permissions()	Ground-truth ACL DRYRUN check against a curated dangerous-command list — would_succeed should always be empty

Setup

pip install redis-guard-mcp
export REDIS_GUARD_URL="redis://readonly_user:password@localhost:6379/0"
redis-guard-mcp

REDIS_GUARD_URL is required — there is no default. Point your MCP client at the redis-guard-mcp command with it set in its env config. See scripts/setup_dev_redis.sh for a working, correctly-ordered example of provisioning the restricted ACL user (+@connection +@read -@write -@admin -@dangerous, plus the three narrow ACL WHOAMI/ACL GETUSER/ACL DRYRUN exceptions redis_check_permissions itself needs — see client.py for why those are safe to grant despite being individually outside @read).

Testing

pip install -e ".[dev]"
scripts/setup_dev_redis.sh   # starts a Redis container + provisions the ACL user + seeds data
pytest tests/ -v

34 tests, almost all against the real local container (a couple of pure config-validation tests need no Redis and skip-check independently); skips automatically if the container isn't reachable. Includes a regression test for the exact CLIENT PAUSE rule-order bug above, and an AST-based structural test asserting the precise set of redis-py methods commands.py calls, so a new tool being added later gets noticed here rather than silently passing review.

Status

v0.1.0. Went through adversarial security review before its first commit, which found and this now fixes: the ACL rule-order bug above (confirmed by actually running CLIENT PAUSE against the shipped setup), two blind spots in the original category-based permission check (now replaced with ACL DRYRUN), unbounded collection reads on a shared Redis instance (now capped/paginated), a non-idempotent dev seed script, and a lazy-singleton thread-safety race in the MCP tool layer.

License

MIT