Next.js DevTools MCP — Use Cases, Install & Live Demo

Name: Next.js DevTools MCP Server
Author: vercel

Why use it

Key features

First-party — maintained by Vercel / Next.js team
nextjs_docs — authoritative doc search, no hallucinations
browser_eval — in-MCP Playwright for testing your app
nextjs_index / nextjs_call — talk to Next 16 dev-server diagnostics

Live Demo

What it looks like in practice

vercel.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vercel": {
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "vercel": {
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "vercel": {
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "vercel": {
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "vercel",
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "vercel": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@vercel/next-devtools-mcp"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add vercel -- npx -y @vercel/next-devtools-mcp

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Next.js DevTools

Upgrade a Next.js project to v16 with guided codemods

👤 Next.js engineers on v14/v15 ⏱ ~60 min advanced

When to use: You've been putting off the Next 16 upgrade. You want an agent to drive codemods and fix async API migrations.

Prerequisites

Next.js project on v14+ — Check package.json
Clean git working tree — git status shows clean — so you can revert if needed

Flow

Run the upgrade tool

Run upgrade_nextjs_16 on this project. Walk me through each codemod before applying.✓ Copied

→ List of planned changes with diffs to preview
Fix async API call sites

After codemods, build the project. For any errors from now-async cookies()/headers(), fix the call sites to use await.✓ Copied

→ Build passes
Enable Cache Components

Run enable_cache_components. Fix any boundary errors it reports.✓ Copied

→ Cache components enabled, app runs

Outcome: A working Next 16 project with Cache Components, in one focused session instead of a scattered week.

Pitfalls

Codemods can't fix custom-patterned async usage — Run the build after each codemod step; fix manually when the codemod tags 'REVIEW' comments
Third-party libs may not be ready for Next 16 — Check package compatibility before upgrading; pin any lib that breaks and file an issue upstream

Combine with: git

Debug a running Next dev server via its diagnostic endpoints

👤 Next.js engineers on v16+ ⏱ ~20 min advanced

When to use: Your next dev is running but something is off (weird hydration, wrong render mode). Next 16+ exposes runtime tools via /_next/mcp.

Prerequisites

Next.js 16+ dev server running — npm run dev

Flow

Discover the server

Run nextjs_index to find my local Next dev servers and list the diagnostic tools they expose.✓ Copied

→ Port + tool list
Call diagnostic tools

Use nextjs_call on port <PORT> to get the route tree and render modes for /dashboard. Is it static, dynamic, or partial?✓ Copied

→ Render mode per route with explanation
Fix the bad render

The /dashboard page uses cookies() making it fully dynamic when I wanted partial prerendering. Find the culprit import and refactor to isolate.✓ Copied

→ Render mode changes to partial after fix

Outcome: Insight into Next's rendering decisions without reading 20 blog posts.

Pitfalls

Dev server diagnostics differ from prod build output — Always verify with next build — dev mode has different defaults

Get authoritative answers to Next.js questions

👤 Next.js devs at any level ⏱ ~10 min beginner

When to use: You have a question about Next.js behavior. You don't want LLM hallucinations — you want a citation.

Flow

Search docs

Use nextjs_docs to find the official guidance on middleware vs route handlers for auth. Return matching sections.✓ Copied

→ Cited doc sections with URLs
Answer with citations

Based only on those sections, which should I use for JWT validation in my Next 16 app, and why? Include doc URLs.✓ Copied

→ Grounded answer with URLs
Apply to my code

Walk through my current implementation in middleware.ts. Does it align with the docs' recommendations?✓ Copied

→ Concrete gap list

Outcome: Authoritative Next.js decisions backed by docs, not vibes.

Pitfalls

Docs lag behind the latest release for a few weeks post-launch — For bleeding-edge features, also check the Next.js RFC / blog posts

Run an E2E check on your Next.js app

👤 Next.js engineers ⏱ ~10 min intermediate

When to use: You just made a change. You want a quick smoke test before committing.

Flow

Navigate and capture

Use browser_eval to open http://localhost:3000/pricing. Screenshot it and capture any console errors.✓ Copied

→ Screenshot + console summary
Click through critical path

Click 'Select Pro plan', verify the checkout modal opens with the right price. Screenshot each step.✓ Copied

→ Pass/fail per step
Report

Summarize: ok / broken / suspicious. If anything failed, paste the console error.✓ Copied

→ Ship-or-don't-ship verdict

Outcome: A quick sanity check embedded in your dev loop — no separate Playwright runner needed.

Pitfalls

browser_eval is Playwright-lite — not a replacement for full E2E suite — Use for quick checks; keep a real Playwright suite for release gates

Combine with: playwright

Combinations

Pair with other MCPs for X10 leverage

vercel + playwright

browser_eval for quick checks, Playwright for full regression suites

Smoke-test /pricing with browser_eval. If that passes, run the Playwright suite on the critical flows.✓ Copied

vercel + git

Upgrade Next, commit at each step

Run upgrade_nextjs_16. After each codemod, commit the diff with a descriptive message so we can bisect if something breaks.✓ Copied

vercel + sentry

Post-upgrade monitor

Deploy the Next 16 build to staging. Watch Sentry for 24h and flag any new errors introduced by async API migration.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
init		First call in a new conversation	free
nextjs_docs	query	Any Next.js factual question	free
browser_eval	actions (navigate, click, screenshot, etc.)	Quick E2E tests of your dev server	free (local browser)
nextjs_index		Discover Next 16+ dev servers	free
nextjs_call	port, tool_name, args	Invoke a Next 16+ runtime diagnostic	free
upgrade_nextjs_16	project_path	Upgrade path from v14/15 to v16	free
enable_cache_components	project_path	Turn on Cache Components in a v16 app	free

Cost & Limits

What this costs to run

API quota: Free — local execution + docs search
Tokens per call: Docs returns can be large; set limit on search
Monetary: Free
Tip: Run init once per session so the agent knows available tools — saves random trial-and-error

Security

Permissions, secrets, blast radius

Credential storage: None — local tool

Data egress: Docs search hits vercel.com; browser_eval goes wherever you navigate; telemetry to vercel (opt-out via NEXT_TELEMETRY_DISABLED)

Troubleshooting

Common errors and fixes

nextjs_index finds no servers

Only Next.js 16+ dev servers expose /_next/mcp. Upgrade first, or use browser_eval for older versions.

Verify: curl http://localhost:3000/_next/mcp

browser_eval fails to launch

Playwright binaries missing. Run npx playwright install once.

Codemod left files in a half-migrated state

Revert via git, then run the codemods one at a time instead of all at once. Commit between each.

nextjs_docs returns irrelevant results

Add the Next.js major version to your query: 'app router middleware in Next 16' instead of just 'middleware'.

Alternatives

Next.js DevTools vs others

Alternative	When to use it instead	Tradeoff
Playwright MCP	You need full Playwright, not the lite browser_eval	More powerful but no Next.js-specific diagnostics or docs search
Cloud Run MCP	You deploy to GCP, not Vercel	Different hosting model; this MCP is Next.js DX-focused, not deploy-focused

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills