nextjs-cache-handler-mcp — Claude Code MCP server
This MCP server lets an AI agent inspect a Next.js Redis cache, trace tag state, model SWR reads, and invalidate tags with a confirmation gate.
claude mcp add --env REDIS_URL=<REDIS_URL> --env DEPLOYMENT_VERSION=<DEPLOYMENT_VERSION> --env HASH_TAG=<HASH_TAG> --transport stdio mcp -- npx -y @leejpsd/nextjs-cache-handler-mcpWhat nextjs-cache-handler-mcp does
The server exposes cache diagnostics for a running Next.js deployment. An agent can test Redis health, search matching keys, decode one entry, and inspect its layer, kind, tags, TTL, age, compression, and size. It can also split a raw Redis key into its namespace parts. tag_state checks invalidation across both cache layers, while simulate_swr predicts whether a read sees fresh, stale, or expired data.
invalidate_tag offers soft and hard invalidation, but remains a dry run until confirm: true is supplied. The process runs on the machine hosting the MCP setup and reaches Redis through REDIS_URL, which is required. DEPLOYMENT_VERSION scopes namespace-aware operations; custom cache handlers may also need CACHE_KEY_PREFIX or ISR_KEY_PREFIX. For AWS ElastiCache, a local process needs an SSH tunnel or bastion into the VPC. Without REDIS_URL, the server cannot connect to Redis.
What it helps with
- check Redis health and cache contents
- search Next.js keys by pattern
- inspect an entry’s tags and TTL
- trace tag invalidation across cache layers
- predict fresh, stale, or expired reads
Example prompts for the agent
- Ask the agent to run
cache_healthand report the Redis status and cached layers. - Use
tag_stateto check whether theproductstag is invalidated on both layers. - Run
simulate_swrfor this entry and explain what a read will do.
How to install nextjs-cache-handler-mcp
Platform CLI
claude mcp add --env REDIS_URL=<REDIS_URL> --env DEPLOYMENT_VERSION=<DEPLOYMENT_VERSION> --env HASH_TAG=<HASH_TAG> --transport stdio mcp -- npx -y @leejpsd/nextjs-cache-handler-mcpReplace <…> with your own values
Platform CLI
codex mcp add mcp --env REDIS_URL=<REDIS_URL> --env DEPLOYMENT_VERSION=<DEPLOYMENT_VERSION> --env HASH_TAG=<HASH_TAG> -- npx -y @leejpsd/nextjs-cache-handler-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@leejpsd/nextjs-cache-handler-mcp"
],
"env": {
"REDIS_URL": "<REDIS_URL>",
"DEPLOYMENT_VERSION": "<DEPLOYMENT_VERSION>",
"HASH_TAG": "<HASH_TAG>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@leejpsd/nextjs-cache-handler-mcp"
],
"env": {
"REDIS_URL": "<REDIS_URL>",
"DEPLOYMENT_VERSION": "<DEPLOYMENT_VERSION>",
"HASH_TAG": "<HASH_TAG>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e REDIS_URL=<REDIS_URL> -e DEPLOYMENT_VERSION=<DEPLOYMENT_VERSION> -e HASH_TAG=<HASH_TAG> mcp npx -y @leejpsd/nextjs-cache-handler-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about nextjs-cache-handler-mcp
How do I install nextjs-cache-handler-mcp in Claude Code?
Run claude mcp add nextjs-cache-handler-mcp -e REDIS_URL=<REDIS_URL> -- npx -y @leejpsd/nextjs-cache-handler-mcp. This registers the server with the required REDIS_URL variable.
What does nextjs-cache-handler-mcp do?
It gives an agent access to Next.js Redis cache diagnostics, including key searches, tag status, SWR simulation, and controlled tag invalidation. Invalidation stays in dry-run mode until confirm: true is passed.
How does it connect to AWS ElastiCache?
A locally running process needs an SSH tunnel or bastion into the VPC, with REDIS_URL aimed at that tunnel. A process inside the VPC can connect directly.
