This MCP server is designed to inspect and operate Next.js Redis caches. It provides functionality for cache health checks, tag state inspection, SWR simulation, and safe invalidation. The goal is to help developers understand cache status and perform controlled cache updates.

🛠️ Key Features

Inspect and operate Next.js Redis caches
Health checks
Tag state inspection
SWR simulation
Safe invalidation

🚀 Use Cases

Verify Redis-backed cache health for Next.js
Check cache tag state to understand invalidation behavior
Simulate SWR behavior for cache-related testing
Invalidate cached entries safely without unintended disruption

⚡ Developer Benefits

Centralized tooling for Next.js Redis cache inspection and control
Supports health, tag state, SWR simulation, and safe invalidation workflows

Setup

Project .mcp.json (Claude Code picks this up automatically):

json

{
  "mcpServers": {
    "nextjs-cache": {
      "command": "npx",
      "args": ["-y", "@leejpsd/nextjs-cache-handler-mcp"],
      "env": {
        "REDIS_URL": "redis://127.0.0.1:6379",
        "DEPLOYMENT_VERSION": "your-deploy-id"
      }
    }
  }
}

Runs locally over stdio and connects to YOUR Redis — nothing is hosted.

AWS/ElastiCache note: ElastiCache is VPC-internal, so a locally running MCP server needs an SSH tunnel/bastion (point REDIS_URL at the tunnel). Agents running inside the VPC (CI, in-cluster) connect directly. Pair with the AWS agent skills/MCP: they handle the infrastructure, this server handles cache semantics.

Tools

Tool

What it answers

Writes?

cache_health

Is Redis up? What's cached, per layer/kind?

cache_search

Which keys match this pattern?

cache_inspect

Decode one entry: kind, age, tags, TTL, compression, sizes

tag_state

Is this tag invalidated right now, on BOTH cache layers?

explain_key

Parse a raw Redis key into layer/kind/namespace/key

simulate_swr

Would this entry be fresh / stale / expired, and what happens on read?

invalidate_tag

Soft (SWR) or hard invalidation — dry-run unless confirm: true

gated

Env: REDIS_URL (required), DEPLOYMENT_VERSION (recommended — scopes namespace-aware tools), CACHE_KEY_PREFIX / ISR_KEY_PREFIX (only when the handlers use custom prefixes).

Install

Configuration

Environment variables

REDIS_URLrequiredsecret

Redis connection string the cache handler uses

DEPLOYMENT_VERSION

Deploy namespace (recommended)

HASH_TAG

Set 'true' when handlers use hashTag: true (Redis Cluster)

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "nextjs-cache-handler-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@leejpsd/nextjs-cache-handler-mcp@0.1.2"
      ],
      "env": {
        "REDIS_URL": "<YOUR_REDIS_URL>",
        "DEPLOYMENT_VERSION": "<YOUR_DEPLOYMENT_VERSION>",
        "HASH_TAG": "<YOUR_HASH_TAG>"
      }
    }
  }
}