scan_keys
Scan Redis database keys safely in batches using the SCAN command to avoid blocking operations on large datasets. Returns partial results with a cursor for continuation.
Instructions
Scan keys in the Redis database using the SCAN command (non-blocking, production-safe).
⚠️ IMPORTANT: This returns PARTIAL results from one iteration. Use scan_all_keys() to get ALL matching keys, or call this function multiple times with the returned cursor until cursor becomes 0.
The SCAN command iterates through the keyspace in small chunks, making it safe to use on large databases without blocking other operations.
Args: pattern: Pattern to match keys against (default is "" for all keys). Common patterns: "user:", "cache:", ":123", etc. count: Hint for the number of keys to return per iteration (default 100). Redis may return more or fewer keys than this hint. cursor: The cursor position to start scanning from (0 to start from beginning). To continue scanning, use the cursor value returned from previous call.
Returns: A dictionary containing: - 'cursor': Next cursor position (0 means scan is complete) - 'keys': List of keys found in this iteration (PARTIAL RESULTS) - 'total_scanned': Number of keys returned in this batch - 'scan_complete': Boolean indicating if scan is finished Or an error message if something goes wrong.
Example usage: First call: scan_keys("user:") -> returns cursor=1234, keys=[...], scan_complete=False Next call: scan_keys("user:", cursor=1234) -> continues from where it left off Final call: returns cursor=0, scan_complete=True when done
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pattern | No | * | |
| count | No | ||
| cursor | No |
Implementation Reference
- src/tools/misc.py:105-157 (handler)The main handler function for the 'scan_keys' tool, decorated with @mcp.tool(). It implements Redis SCAN for paginated key scanning with pattern matching, cursor support, and error handling.@mcp.tool() async def scan_keys( pattern: str = "*", count: int = 100, cursor: int = 0 ) -> Union[str, Dict[str, Any]]: """ Scan keys in the Redis database using the SCAN command (non-blocking, production-safe). ⚠️ IMPORTANT: This returns PARTIAL results from one iteration. Use scan_all_keys() to get ALL matching keys, or call this function multiple times with the returned cursor until cursor becomes 0. The SCAN command iterates through the keyspace in small chunks, making it safe to use on large databases without blocking other operations. Args: pattern: Pattern to match keys against (default is "*" for all keys). Common patterns: "user:*", "cache:*", "*:123", etc. count: Hint for the number of keys to return per iteration (default 100). Redis may return more or fewer keys than this hint. cursor: The cursor position to start scanning from (0 to start from beginning). To continue scanning, use the cursor value returned from previous call. Returns: A dictionary containing: - 'cursor': Next cursor position (0 means scan is complete) - 'keys': List of keys found in this iteration (PARTIAL RESULTS) - 'total_scanned': Number of keys returned in this batch - 'scan_complete': Boolean indicating if scan is finished Or an error message if something goes wrong. Example usage: First call: scan_keys("user:*") -> returns cursor=1234, keys=[...], scan_complete=False Next call: scan_keys("user:*", cursor=1234) -> continues from where it left off Final call: returns cursor=0, scan_complete=True when done """ try: r = RedisConnectionManager.get_connection() cursor, keys = r.scan(cursor=cursor, match=pattern, count=count) # Convert bytes to strings if needed decoded_keys = [ key.decode("utf-8") if isinstance(key, bytes) else key for key in keys ] return { "cursor": cursor, "keys": decoded_keys, "total_scanned": len(decoded_keys), "scan_complete": cursor == 0, } except RedisError as e: return f"Error scanning keys with pattern '{pattern}': {str(e)}"