# nextjs-cache-handler MCP server

> Allows AI agents to inspect and operate Next.js Redis caches, including health checks, tag state verification, and safe cache invalidation.

- Repository: https://github.com/leejpsd/nextjs-cache-handler
- Page: https://hostedmcp.org/servers/leejpsd/nextjs-cache-handler-mcp
- Transport: stdio
- Stars: 6
- License: MIT
- Latest version: 0.1.2

## Install

### Claude Code

```sh
claude mcp add --env 'REDIS_URL=<YOUR_REDIS_URL>' nextjs-cache-handler-mcp -- npx -y @leejpsd/nextjs-cache-handler-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "nextjs-cache-handler-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@leejpsd/nextjs-cache-handler-mcp"
      ],
      "env": {
        "REDIS_URL": "<YOUR_REDIS_URL>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "nextjs-cache-handler-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@leejpsd/nextjs-cache-handler-mcp"
      ],
      "env": {
        "REDIS_URL": "<YOUR_REDIS_URL>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"nextjs-cache-handler-mcp","type":"stdio","command":"npx","args":["-y","@leejpsd/nextjs-cache-handler-mcp"],"env":{"REDIS_URL":"<YOUR_REDIS_URL>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "nextjs-cache-handler-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@leejpsd/nextjs-cache-handler-mcp"
      ],
      "env": {
        "REDIS_URL": "<YOUR_REDIS_URL>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add nextjs-cache-handler-mcp --env 'REDIS_URL=<YOUR_REDIS_URL>' -- npx -y @leejpsd/nextjs-cache-handler-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.nextjs-cache-handler-mcp]
command = "npx"
args = ["-y", "@leejpsd/nextjs-cache-handler-mcp"]

[mcp_servers.nextjs-cache-handler-mcp.env]
REDIS_URL = "<YOUR_REDIS_URL>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'REDIS_URL=<YOUR_REDIS_URL>' nextjs-cache-handler-mcp npx -- -y @leejpsd/nextjs-cache-handler-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "nextjs-cache-handler-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@leejpsd/nextjs-cache-handler-mcp"
      ],
      "env": {
        "REDIS_URL": "<YOUR_REDIS_URL>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `REDIS_URL` | yes | yes | Redis connection string the cache handler uses |
| `DEPLOYMENT_VERSION` | no | no | Deploy namespace (recommended) |
| `HASH_TAG` | no | no | Set 'true' when handlers use hashTag: true (Redis Cluster) |

## Tools (7)

- `cache_health`: Ping Redis and summarize cache key counts per layer/kind. First tool to run when debugging cache issues.
- `cache_search`: Scan cache keys by glob pattern (e.g. 'next-incremental:entry:*/blog*'). Returns up to `limit` keys.
- `cache_inspect`: Decode a cache entry: kind, timestamps, tags, TTL, sizes, compression. Values are summarized, never dumped in full.
- `tag_state`: Show invalidation state for a tag across BOTH cache layers: the ISR tag state (stale/expired timestamps) and the 'use cache' tag-expiration marker. Answers 'is this tag invalidated right now, and since when?'
- `explain_key`: Parse a Redis key into layer / kind / namespace / cache key.
- `simulate_swr`: Given entry timing values, classify freshness the way the handler does (fresh / stale / expired) and explain what a read would do.
- `invalidate_tag`: Invalidate a tag across both layers. DRY-RUN by default: shows exactly what would be written/deleted. Pass confirm=true to execute. mode 'soft' = stale-while-revalidate (revalidateTag(tag,'max') semantics); 'hard' = delete entries now.

## FAQ

### How do I connect to AWS ElastiCache?

Since ElastiCache is VPC-internal, you must use an SSH tunnel or bastion and point your REDIS_URL at that tunnel.

### Is the cache invalidation tool dangerous?

The invalidate_tag tool performs a dry-run by default unless you explicitly set confirm to true.

### Does this server host my data?

No, the server runs locally over stdio and connects directly to your own Redis instance.
