Allows AI agents to inspect and operate Next.js Redis caches, including health checks, tag state verification, and safe cache invalidation.
Also known as leejpsd/nextjs-cache-handler, @leejpsd/nextjs-cache-handler-mcp
- Stars
- 6
- Tools
- 7
- Downloads, 30 days
- 357
- Latest version
- 0.1.2
- Last commit
- Nov 13, 2026
- License
- MIT
What is nextjs-cache-handler MCP?
nextjs-cache-handler allows AI agents to inspect and operate Next.js Redis caches, including health checks, tag state verification, and safe cache invalidation. It exposes 7 tools, such as cache_health, cache_search, cache_inspect.
Summary generated from the project's README
About nextjs-cache-handler MCP server
Debugging Next.js cache issues from within an AI agent becomes a structured process instead of guesswork. Developers using Claude Code or Cursor can connect this server to their local or remote Redis instances to inspect, verify, and manage cache states. By providing a REDIS_URL and an optional DEPLOYMENT_VERSION, the server allows agents to interact with the specific cache semantics used by the @leejpsd/nextjs-cache-handler package.
The server operates locally via stdio and connects directly to your existing Redis infrastructure. If you are using AWS ElastiCache, you can connect by pointing the REDIS_URL to an SSH tunnel or bastion. The toolset includes specific commands like cache_health to check connectivity, tag_state to verify if a tag is invalidated across both cache layers, and simulate_swr to predict if an entry is fresh or stale. For making changes, the invalidate_tag tool allows for soft or hard invalidation, though it requires a confirm flag to prevent accidental writes.
Written from the project's README. Every use case is checked against a quote from it.
How to install nextjs-cache-handler MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall nextjs-cache-handler MCP in Claude Code
$ claude mcp add --env 'REDIS_URL=<YOUR_REDIS_URL>' nextjs-cache-handler-mcp -- npx -y @leejpsd/nextjs-cache-handler-mcpInstall nextjs-cache-handler MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"nextjs-cache-handler-mcp": {
"command": "npx",
"args": [
"-y",
"@leejpsd/nextjs-cache-handler-mcp"
],
"env": {
"REDIS_URL": "<YOUR_REDIS_URL>"
}
}
}
}Install nextjs-cache-handler MCP in VS Code
.vscode/mcp.json
{
"servers": {
"nextjs-cache-handler-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@leejpsd/nextjs-cache-handler-mcp"
],
"env": {
"REDIS_URL": "<YOUR_REDIS_URL>"
}
}
}
}Install nextjs-cache-handler MCP in VS Code CLI
$ 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>"}}'Install nextjs-cache-handler MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"nextjs-cache-handler-mcp": {
"command": "npx",
"args": [
"-y",
"@leejpsd/nextjs-cache-handler-mcp"
],
"env": {
"REDIS_URL": "<YOUR_REDIS_URL>"
}
}
}
}Install nextjs-cache-handler MCP in Codex
$ codex mcp add nextjs-cache-handler-mcp --env 'REDIS_URL=<YOUR_REDIS_URL>' -- npx -y @leejpsd/nextjs-cache-handler-mcpInstall nextjs-cache-handler MCP in Codex config.toml
~/.codex/config.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>"
Install nextjs-cache-handler MCP in Gemini CLI
$ gemini mcp add -s user -e 'REDIS_URL=<YOUR_REDIS_URL>' nextjs-cache-handler-mcp npx -- -y @leejpsd/nextjs-cache-handler-mcpInstall nextjs-cache-handler MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"nextjs-cache-handler-mcp": {
"command": "npx",
"args": [
"-y",
"@leejpsd/nextjs-cache-handler-mcp"
],
"env": {
"REDIS_URL": "<YOUR_REDIS_URL>"
}
}
}
}nextjs-cache-handler MCP tools 7
Detected from the READMEcache_healthcache_searchcache_inspecttag_stateexplain_keysimulate_swrinvalidate_tag
| cache_health | — | |
| cache_search | — | |
| cache_inspect | — | |
| tag_state | — | |
| explain_key | — | |
| simulate_swr | — | |
| invalidate_tag | — |
Configuration
REDIS_URLRequiredSecretRedis connection string the cache handler uses
DEPLOYMENT_VERSIONDeploy namespace (recommended)
HASH_TAGSet 'true' when handlers use hashTag: true (Redis Cluster)
| Name | Description | |
|---|---|---|
| REDIS_URL | Redis connection string the cache handler uses | RequiredSecret |
| DEPLOYMENT_VERSION | Deploy namespace (recommended) | |
| HASH_TAG | Set 'true' when handlers use hashTag: true (Redis Cluster) |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@leejpsd/nextjs-cache-handler-mcp
MCP (Model Context Protocol) server for
@leejpsd/nextjs-cache-handler
Redis caches. Lets AI agents (Claude Code, Cursor, …) inspect and operate a
running deployment's Next.js cache: "why isn't this page updating?"
becomes a tag_state call instead of guesswork.
Setup
Project .mcp.json (Claude Code picks this up automatically):
{
"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? | no |
cache_search |
Which keys match this pattern? | no |
cache_inspect |
Decode one entry: kind, age, tags, TTL, compression, sizes | no |
tag_state |
Is this tag invalidated right now, on BOTH cache layers? | no |
explain_key |
Parse a raw Redis key into layer/kind/namespace/key | no |
simulate_swr |
Would this entry be fresh / stale / expired, and what happens on read? | no |
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).
nextjs-cache-handler MCP questions
How do I add nextjs-cache-handler MCP to Claude Code?
Run claude mcp add --env 'REDIS_URL=<YOUR_REDIS_URL>' nextjs-cache-handler-mcp -- npx -y @leejpsd/nextjs-cache-handler-mcp in your terminal. Add --scope user to make it available in every project.
How do I add nextjs-cache-handler MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does nextjs-cache-handler MCP provide?
It exposes 7 tools, including cache_health, cache_search, cache_inspect, tag_state, explain_key.
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.