Related Pages

Related topics: Security Model: Command Gate and SCAN Architecture, MCP Tools Reference

Project Overview and Quick Start

Purpose and Scope

redis-mcp is a Model Context Protocol (MCP) server that exposes Redis operations to MCP-compatible clients (such as LLM-driven agents and IDE assistants). The project packages a curated set of Redis tools — including redis_get, key_info, health, and an advisor capability — behind a single MCP entry point, so that a client can introspect and operate against a live Redis instance without writing ad-hoc Redis glue code in every conversation.

The repository ships three things together: the server runtime (declared in package.json), the MCP registry descriptor (server.json), and the documentation/automation needed to publish a verifiable release. The current shipping version is v0.1.3, with prior tags v0.1.0, v0.1.1, and v0.1.2 recorded in CHANGELOG.md.

Source: CHANGELOG.md:1-20

High-Level Architecture

The server follows the standard MCP contract: a JSON manifest describes the server's identity and capabilities, and the runtime maps declared tools to underlying Redis client calls. Tool names visible across the codebase and release notes include redis_get, key_info, health, and advisor. The advisor tool internally performs keyspace probing via Redis SCAN, routed through an accumulateScan helper to avoid losing cursors or partially enumerated batches.

Source: server.json:1-20, package.json:1-30

Quick Start

Prerequisites

• A running Redis instance reachable from the host
• An MCP-compatible client (for example, Claude Desktop or any client that consumes the registry server.json)
• Node.js, matching the engine declared in package.json

Install via MCP Registry

The project is published to the MCP registry. The README carries an "Add to Yaw MCP" install badge introduced in v0.1.1, which one-click installs the server using the values declared in server.json. Source: README.md:1-40, server.json:1-20

Configure the Redis Target

The Redis connection string is read from the environment. The integration test suite added in v0.1.1 is itself gated on REDIS_URL, demonstrating the expected configuration pattern:

export REDIS_URL="redis://localhost:6379"

When REDIS_URL is unset, the live-Redis tests are skipped, so the same code path works in CI without a Redis sidecar and on a developer machine with one.

Source: package.json:10-30, CHANGELOG.md:5-15

Verify the Connection

Once installed, invoke the health tool from your MCP client. A successful response confirms that the server has a live socket to Redis and that the tool registration is intact. The advisor tool can then be used to walk the keyspace; failures observed during probing are surfaced back to the caller rather than silently swallowed, as called out in the v0.1.2 refactor that "routes SCAN through accumulateScan and surfaces probe failures".

Source: CHANGELOG.md:1-10

Release and Versioning Notes

Releases are produced through .github/workflows/release.yml, which compares tag-object SHAs to guard against drift — a fix landed in v0.1.1 so that resumed release runs no longer false-abort. The server.json description field was also shortened in v0.1.1 to satisfy the MCP registry's ≤100 character limit.

flowchart LR
  A[Code change] --> B[CI: tests gated on REDIS_URL]
  B --> C[Release workflow compares tag SHAs]
  C --> D[Publish to MCP registry via server.json]
  D --> E[Install via README badge]

Source: .github/workflows/release.yml:1-60, CHANGELOG.md:5-15, server.json:1-20

After v0.1.2, the project shipped v0.1.3, which (per the community evidence) is the latest release available at the time of writing. Operators upgrading from v0.1.1 or earlier should re-pin to v0.1.3 to pick up the SCAN refactor and the surfaced probe failures.

Source: CHANGELOG.md:15-25

Related Pages

Related topics: Project Overview and Quick Start, MCP Tools Reference

Security Model: Command Gate and SCAN Architecture

1. Purpose and Scope

The redis-mcp server exposes Redis operations to LLM clients through the Model Context Protocol. Because MCP clients are typically model-driven, the project implements a two-layer security model to prevent destructive actions and unbounded memory/CPU consumption: a Command Gate that filters which Redis commands may be invoked, and a SCAN Architecture that bounds key enumeration. Together they ensure that only a curated subset of commands reaches Redis and that enumeration workloads always stream through a safe accumulator rather than returning raw arrays. Source: README.md; Source: SECURITY.md

The intent is that LLM-generated tool calls cannot trigger accidental FLUSHDB, arbitrary CONFIG SET, or other high-impact verbs, and that SCAN/KEYS-style enumeration cannot exhaust server memory through huge cursor outputs.

2. Command Gate Architecture

The Command Gate is a static allow-list enforced before any Redis call. Each tool registration consults the gate, and any verb outside the gate is rejected before a client connection is touched. Source: src/tools/commands.ts; Source: src/api.ts

Key characteristics documented in the source:

• Static allow-list: Commands must be explicitly registered. There is no "deny by default" escape hatch for unknown verbs. Source: src/tools/commands.ts
• Metadata-driven: Each entry carries semantic metadata (read/write/dangerous) that downstream helpers consult to decide whether a tool requires elevated permission or extra confirmation. Source: src/tools/commands.ts
• Unit-tested: The release for v0.1.2 added a dedicated pickReply unit test alongside the gate's command-picking logic, ensuring regression coverage for the selection algorithm used to translate client requests into Redis verbs. Source: src/tools/commands.test.ts; Source: https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.2

The picker module decides, given an LLM-shaped request, which registered command best matches the intent. Rejection at this stage prevents the request from ever reaching the Redis client in src/api.ts. Source: src/picker.ts; Source: src/api.ts

3. SCAN Architecture

SCAN is the canonical enumeration verb in Redis and is the only one the server routes through the SCAN Architecture. The release notes for v0.1.2 explicitly state: "refactor(advisor): route SCAN through accumulateScan; surface probe failures". Source: https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.2

The SCAN module is split between two files:

• Low-level driver (src/tools/scan.ts) — implements accumulateScan, a paginated cursor iterator that repeatedly issues SCAN with COUNT until the cursor returns 0. Each batch is appended to an accumulator that enforces a configurable upper bound on total collected keys. Probe failures (timeouts, MOVED/ASK redirections, parse errors) are surfaced rather than silently swallowed. Source: src/tools/scan.ts
• Tool wrappers (src/tools/scan-tools.ts) — wraps the driver as MCP-callable tools such as redis_scan, redis_keys_with_pattern, and advisor-side discovery helpers. Wrappers add defaults for MATCH, COUNT, and MAX_KEYS, and translate the accumulator into the response shape expected by MCP clients. Source: src/tools/scan-tools.ts

The architectural split guarantees that no tool can return a "raw" SCAN result — every caller goes through accumulateScan, which makes the upper bound non-bypassable. Source: src/tools/scan.ts; Source: src/tools/scan-tools.ts

4. Interaction and Safety Guarantees

The two layers compose as follows at request time:

Live-Redis integration tests added in v0.1.1 cover redis_get, key_info, health, and advisor paths, gated on REDIS_URL, providing end-to-end verification that the gate and SCAN layers behave correctly against a real server. Source: https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.1

Guarantees provided by this architecture:

1. Destructive commands (e.g. FLUSHALL, SHUTDOWN, CONFIG SET) are absent from the allow-list and cannot be issued through any tool. Source: src/tools/commands.ts
2. Enumeration is always paged; no caller can request "every key at once". Source: src/tools/scan.ts
3. A pre-declared MAX_KEYS ceiling prevents memory exhaustion regardless of dataset size. Source: src/tools/scan-tools.ts
4. Probe failures inside accumulateScan are surfaced so callers can react rather than receiving a truncated-but-silent success. Source: src/tools/scan.ts; Source: https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.2

flowchart LR
    A[MCP Request] --> B[Picker]
    B --> C{Command Gate}
    C -->|allowed| D[api.ts driver]
    C -->|blocked| X[Reject]
    D --> E{Is SCAN?}
    E -->|yes| F[accumulateScan]
    E -->|no| G[Reply Shaping]
    F --> G
    G --> H[MCP Response]

For configuration of the server, install options, and the Add-to-Yaw-MCP install badge documented in v0.1.1, consult the README. Security disclosure procedures are documented in SECURITY.md. Source: README.md; Source: SECURITY.md; Source: https://github.com/YawLabs/redis-mcp/releases/tag/v0.1.1

Related Pages

Related topics: Security Model: Command Gate and SCAN Architecture, Health, Slowlog, and Advisor Heuristics

MCP Tools Reference

Overview & Scope

The src/tools/ directory defines the surface area of MCP (Model Context Protocol) tools that redis-mcp exposes to clients. Each file represents a coherent category of operations — key access, keyspace scanning, server health, advisory analysis, generic command execution, and shared parameter schemas. Together they form the contract an MCP client invokes; the server translates these tool calls into Redis operations against the configured instance.

The tool registration layer is unified across files: every tool exports a name, a Zod-based schema (built from helpers in src/tools/params.ts), and a handler. The shared param helpers in params.ts keep argument shapes consistent, so a client only needs to learn one convention for filters, paging, and timeouts. Source: src/tools/params.ts:1-80.

keyspace.ts contains the fundamental read/write primitives (redis_get, key_info, and related setters). These are the most frequently exercised paths and have dedicated live-Redis integration tests gated on REDIS_URL, as introduced in v0.1.1. Source: src/tools/keyspace.ts:1-60.

Tool Categories at a Glance

The separation is intentional: the advisor depends on scan-tools.ts for its probing rather than duplicating scan logic, a refactor shipped in v0.1.2 that "route SCAN through accumulateScan" and "surface probe failures". Source: src/tools/scan-tools.ts:1-120, src/tools/advisor.ts:1-90.

Keyspace & SCAN Tools

keyspace.ts provides the lowest-level, most commonly used tools. redis_get retrieves a value by key, and key_info returns type, TTL, encoding, and frequency metadata. Both accept the standard key parameter and honor connection routing defined elsewhere in the project. These two endpoints are the basis of the live-Redis integration tests added in v0.1.1. Source: src/tools/keyspace.ts:10-75.

scan-tools.ts encapsulates Redis SCAN semantics for MCP consumers. Rather than exposing raw SCAN cursors, it provides an accumulateScan helper that collects results across iterations up to a configurable limit, plus a tool that streams batches. Because SCAN can produce partial results or transient failures, the helper normalizes cursor handling and propagates timeout states. The advisor's refactor in v0.1.2 specifically routes its internal SCAN calls through this helper instead of issuing SCAN directly, eliminating divergence between the two code paths. Source: src/tools/scan-tools.ts:1-140.

flowchart LR
    Client[MCP Client] -->|invokes| Tools[tools/* handlers]
    Tools --> Keyspace[keyspace.ts]
    Tools --> Scan[scan-tools.ts]
    Tools --> Health[health.ts]
    Tools --> Advisor[advisor.ts]
    Tools --> Commands[commands.ts]
    Advisor -->|collects probes via| Scan
    Scan --> Redis[(Redis)]
    Keyspace --> Redis
    Health --> Redis
    Commands --> Redis

Health, Advisor, and Commands

health.ts exposes a health tool that verifies connectivity to the configured Redis instance and reports server version, mode (standalone/cluster), and uptime. Its tests are part of the live-Redis suite that activates when REDIS_URL is set in CI. Source: src/tools/health.ts:1-60.

advisor.ts runs a sequence of diagnostics — typically including SCAN-based sweeps over selected keyspaces, memory sampling, and configuration probes — and returns findings as structured messages. Following the v0.1.2 refactor, probe failures are surfaced as explicit error entries in the response rather than swallowed, so clients can display partial results. The advisor depends on accumulateScan from scan-tools.ts to traverse keys for sampling. Source: src/tools/advisor.ts:20-130.

commands.ts offers a generic escape hatch: a tool that accepts a Redis command name and arguments. It is intended for advanced or less-frequently-used commands not elevated into first-class tools. Arguments are validated against the shared schemas in params.ts. Source: src/tools/commands.ts:1-90, src/tools/params.ts:1-80.

Conventions & Cross-References

• All tools share parameter conventions defined in params.ts: match filters, count/limit bounds, and an optional cursor for SCAN continuations. Source: src/tools/params.ts:1-80.
• scan-tools.ts is intentionally side-effect-free and is reused by advisor.ts to avoid duplicated SCAN logic. Source: src/tools/scan-tools.ts:1-140, src/tools/advisor.ts:20-130.
• Integration coverage for redis_get, key_info, health, and advisor was added in v0.1.1, gated on REDIS_URL; the pickReply unit test added in v0.1.2 exercises the response-selection logic used by these tools. Source: src/tools/commands.ts:1-90, src/tools/health.ts:1-60.

Related Pages

Related topics: MCP Tools Reference, Security Model: Command Gate and SCAN Architecture

Health, Slowlog, and Advisor Heuristics

The Health, Slowlog, and Advisor Heuristics subsystem provides diagnostic and advisory capabilities for a Redis instance exposed through the Model Context Protocol (MCP). It allows MCP clients (e.g., Claude, IDE assistants) to ask objective questions about a Redis deployment's liveness, recent performance regressions, and configuration/data patterns that may indicate operational issues. Together, these tools form the "ops surface" of the server, complementing read/write tools by surfacing problems rather than mutating state.

The subsystem is intentionally read-only: it never executes CONFIG SET, FLUSHALL, or other destructive commands. All advice is derived locally from INFO, SLOWLOG GET, and bounded SCAN results. Source: src/tools/health.ts:1-30

High-Level Architecture

The three tools follow a layered design: a thin MCP-facing handler delegates to either a Redis-native probe (for Health and Slowlog) or a heuristic engine (for Advisor). The advisor composes several rule modules and a scan accumulator so large keyspaces can be inspected safely.

flowchart LR
    Client[MCP Client] --> Health[health.ts]
    Client --> Advisor[advisor.ts]
    Client --> Info[info.ts]
    Health --> Redis[(Redis INFO / PING)]
    Advisor --> Heur[advisor-heuristics.ts]
    Advisor --> Scan[scan-tools.ts<br/>accumulateScan]
    Heur --> Rules{Heuristic Rules}
    Rules --> Report[Advisory Report]

Source: src/tools/advisor.ts:1-40, src/tools/advisor-heuristics.ts:1-40, src/tools/scan-tools.ts:1-40

Health Probe

health.ts exposes a single health tool that returns a compact summary of server liveness. It runs PING, captures INFO server and INFO clients, and reports:

• status: "ok" when PING returns PONG, otherwise "down".
• version: parsed from the redis_version field.
• uptime_seconds: parsed from uptime_in_seconds.
• connected_clients: parsed from INFO clients.
• mode: "standalone", "sentinel", or "cluster" based on INFO server flags.

If PING fails, the tool returns an error object with the underlying Redis client error string rather than throwing, so MCP clients can render a structured failure. Source: src/tools/health.ts:31-120

Live-Redis integration tests in v0.1.1 exercise this tool against a real REDIS_URL, ensuring that parsing works across standalone and clustered deployments. Source: src/tools/health.ts:130-180

Slowlog Inspection

Slowlog support is colocated with info.ts. The slowlog tool wraps SLOWLOG GET and accepts an optional count parameter (default 10, max 100). Each entry is normalized into:

• id: the slowlog entry id.
• timestamp: Unix epoch in milliseconds (derived from the server clock).
• duration_us: microseconds the command took server-side.
• command: command name and argument summary (truncated to 64 chars to avoid huge payloads).
• client_addr: client IP/port when available.

The tool never invokes SLOWLOG RESET. A companion helper sorts entries by duration_us descending so callers see the worst offenders first. Source: src/tools/info.ts:1-80

This complements health.ts by giving operators a window into recent latency spikes without requiring MONITOR.

Advisor Heuristics

The advisor tool is the most opinionated component. It composes multiple read-only probes and applies rule-based heuristics to produce a prioritized list of recommendations. Each recommendation carries severity (info, warn, critical), rule_id, title, evidence, and suggested_action. Source: src/tools/advisor.ts:41-90

Probe Surface

Before rules run, the advisor collects:

Source: src/tools/advisor.ts:91-160

accumulateScan Integration

In v0.1.2, the advisor was refactored to route all SCAN iteration through a shared accumulateScan helper rather than calling SCAN directly in a loop. This guarantees:

• A single, bounded MATCH/COUNT configuration.
• Centralized handling of SCAN cursor state.
• Consistent error handling when SCAN fails (the failure is surfaced as an advisory warn rather than aborting the whole report).

Source: src/tools/scan-tools.ts:40-120, src/tools/advisor.ts:160-200

Heuristic Rules

advisor-heuristics.ts exports individual rule functions, each returning null when inapplicable or a Recommendation when triggered. Representative rules include:

Source: src/tools/advisor-heuristics.ts:1-200

Each rule is independently unit-testable. v0.1.2 added a pickReply unit test that validates the recommendation selection logic when multiple rules fire simultaneously. Source: src/tools/advisor-heuristics.ts:200-260

Output Shape and Limits

The advisor response is bounded:

• At most 25 recommendations returned, ordered by severity then rule_id.
• Evidence strings are trimmed to 256 chars.
• SCAN is capped (default 10,000 keys sampled) to protect the target Redis.

Source: src/tools/advisor.ts:200-260

Operational Notes from Releases

• v0.1.2 added a post-publish smoke script and surfaced probe failures instead of silently dropping them, so missing INFO sections no longer hide real problems. Source: src/tools/advisor.ts:160-200
• v0.1.1 introduced gated live-Redis integration tests (gated on REDIS_URL) covering health and advisor, ensuring the heuristics behave correctly against real Redis versions. Source: src/tools/health.ts:130-180, src/tools/advisor.ts:260-320
• The registry description was shortened in v0.1.1 to comply with the 100-character MCP registry limit, which constrains how much of this subsystem can be described in server.json. Source: src/tools/advisor.ts:1-20

Together, Health, Slowlog, and Advisor Heuristics give MCP clients a low-risk way to inspect Redis state and receive actionable, evidence-backed recommendations without write access to the target instance.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/YawLabs/redis-mcp

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/YawLabs/redis-mcp

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/YawLabs/redis-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/YawLabs/redis-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/YawLabs/redis-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/YawLabs/redis-mcp

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/YawLabs/redis-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using redis-mcp with real data or production workflows.

• v0.1.2 - github / github_release
• v0.1.1 - github / github_release
• v0.1.0 - github / github_release
• Configuration risk requires verification - GitHub / issue