Next.js DevTools MCP With Claude Code: Complete Setup

Next.js DevTools MCP lets Claude Code inspect a running Next.js application instead of reasoning only from source files. It can retrieve current errors and logs, inspect routes and project metadata, look up Server Actions, query framework knowledge, and help verify changes in the browser.

The setup takes one JSON entry. The improvement comes from changing your workflow so runtime evidence is required before the agent says a task is complete.

What Next.js DevTools MCP exposes

Next.js 16 includes a development MCP endpoint inside the running application. The next-devtools-mcp package discovers compatible local instances and presents their capabilities to MCP clients such as Claude Code.

The official Next.js MCP documentation lists:

• Build, runtime, and type error retrieval
• Development log access
• Page and project metadata
• Server Action lookup
• Next.js documentation and best-practice knowledge
• Migration and upgrade tooling
• Browser testing integration

This is development tooling, not a production backdoor. Use it while the local development server is running.

Requirements

You need:

• Next.js 16 or later
• A working Node.js and package manager environment
• Claude Code
• A project-scoped .mcp.json
• A running Next.js development server

Check the application version:

node -p "require('./node_modules/next/package.json').version"

If the package is missing, install dependencies first. If the app is on Next.js 15, upgrade before expecting the built-in development endpoint.

Add next-devtools-mcp to Claude Code

Create .mcp.json in the project root:

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

The @latest tag follows the official Next.js setup and keeps the bridge aligned with current framework tooling. In a tightly controlled environment, pin a tested version and update it through normal dependency review.

Start the app:

npm run dev

Then restart Claude Code or reload its MCP configuration. Project-scoped servers require trust because .mcp.json can launch a local command.

Check the connection:

claude mcp list

Inside Claude Code, open:

/mcp

The server should appear as connected or ready. Ask it to discover the app:

Use Next.js DevTools MCP to discover every running Next.js instance.
Report project metadata and current errors. Do not edit files.

Use live errors as the first debugging step

Without runtime access, an agent often begins by searching for code that looks suspicious. With DevTools MCP, it can start from the actual failure.

Use:

Query the running Next.js app for current errors.
For each error, identify the route, error class, and likely source file.
Do not change code until you have traced the evidence.

If the browser reports a hydration mismatch, Claude can retrieve that error, inspect the affected route and component boundary, then propose a focused fix. After editing, query the errors again.

That closed loop is better than "fix hydration" because it preserves the before-and-after evidence.

Inspect logs without pasting them into chat

The MCP server can return the development log path. Ask:

Use Next.js DevTools MCP to locate the development logs.
Read only the entries related to the current /settings request
and summarize the first causal error.

This avoids dumping an entire terminal history into the context window. It also gives Claude the current log file even when the dev server runs in another terminal.

Keep secrets out of application logs. MCP makes logs easier to consume, which also makes careless logging easier to expose to the model.

Query route and page metadata

For unfamiliar applications:

Inspect the project and page metadata for /dashboard.
Explain which route, layouts, and relevant components participate.
Then identify the smallest boundary for adding an empty state.

Metadata does not replace reading source. It helps the agent start at the route the runtime actually rendered.

For Server Actions:

Look up the Server Action referenced by this runtime error.
Find its source and trace authorization and validation before proposing a fix.

This is especially useful when a production-style action identifier appears in an error and the source function is not obvious from the message.

Verify a feature after implementation

A useful completion prompt is explicit:

Verify the account settings feature.

1. Run typecheck and the targeted tests.
2. Start or reuse the Next.js dev server.
3. Query Next.js DevTools MCP for current errors.
4. Open /settings in the browser.
5. Test loading, success, validation failure, and unauthorized states.
6. Query runtime errors again.
7. Report the commands, routes, and observed results.

Do not say "verified" without the evidence.

The MCP server can surface errors and metadata. A browser tool supplies interaction and screenshots. Use both when visual or user-flow behavior matters.

Next.js documents Playwright MCP integration as part of the development toolchain. Keep browser access narrowly scoped to test environments and non-production credentials.

Use MCP for a Next.js 16 upgrade

The official Next.js 16 upgrade guide recommends Next.js DevTools MCP for agent-assisted migrations.

Start in Claude Code Plan Mode:

/plan

Inspect the installed Next.js version, configuration, routing,
request APIs, caching, and proxy or middleware usage.
Use the Next.js MCP knowledge and upgrade tools.
Separate automated codemods from decisions that require review.
Return a migration, verification, rollout, and rollback plan.

Approve the plan, run the migration in small steps, and use the live error endpoint after each meaningful stage. Do not combine dependency upgrade, codemods, cache redesign, and unrelated feature changes in one diff.

Troubleshoot a missing connection

The server is absent

Confirm .mcp.json is at the project root and valid:

jq empty .mcp.json
claude mcp list

Claude Code prompts before trusting project MCP commands. Reset or review project choices if the server was previously denied.

npx cannot start

Test the exact command:

npx -y next-devtools-mcp@latest --help

If Claude Code cannot resolve npx, use the correct absolute path or fix the environment that launches Claude Code.

The MCP server connects but finds no app

Start the Next.js development server and confirm it is version 16 or later. Restart a server that was already running before the MCP configuration was added.

npm run dev

Then ask the MCP server to discover instances again.

Tools appear but return no browser state

Open the target page in a browser. Some runtime information exists only after the application has served or rendered the route.

Several apps are running

Ask the server to list every discovered instance and identify each port and project root before calling a route-specific tool.

Pair MCP with agent instructions

MCP gives Claude live evidence. It does not explain your preferred architecture.

Use a small AGENTS.md to point coding agents to version-matched documentation and a CLAUDE.md to define project boundaries, commands, and verification expectations. The Next.js CLAUDE.md and AGENTS.md setup provides a production template.

The three layers are complementary:

Next.js DevTools MCP FAQs

Does this work with Cursor and other coding agents?

It works with MCP-compatible coding agents. The exact configuration and approval interface depends on the client.

Can I use it against production?

The documented workflow targets the Next.js development server. Do not expose development MCP endpoints as an unauthenticated production control surface.

Does it replace Playwright?

No. DevTools MCP exposes framework runtime information. Playwright drives and observes browser behavior. Use both for end-to-end verification.

Should I commit .mcp.json?

Commit the project configuration when every contributor should have the tool and the entry contains no secrets. Review it like executable configuration because it launches a package.

Why use @latest in the config?

The official setup uses it to follow active Next.js tooling. Security-sensitive or reproducible environments may prefer a pinned, reviewed version.

Build This Now uses the same evidence loop across the rest of a product: inspect the architecture, implement within its boundaries, then verify the live system instead of trusting source code alone.

Next.js DevTools MCP is valuable because it makes the agent answer a harder question than "does this code look right?" It asks "what did the application actually do?"

Posted by @speedy_devv