Next.js DevTools MCP

Requirements: Node.js v20.19+, npm or pnpm, Next.js 16+ for runtime diagnostics.

Total capabilities: 7 Tools + 2 Prompts + 17 Resources = 26 available features.

Tool naming: All tools follow mcp__plugin_next-devtools_next-devtools__<tool-name> . This file uses abbreviated names for brevity.

See references/tools-reference.md for the complete tools table and nextjs_call tool names.

Tools (7)

Tool Purpose

init

Initialize MCP context with documentation-first behavior

nextjs_index

Discover running Next.js dev servers and available MCP tools

nextjs_call

Call a specific MCP tool on a running Next.js dev server

nextjs_docs

Fetch Next.js official documentation by path

browser_eval

Playwright browser automation for testing

enable_cache_components

Migrate to Next.js 16 Cache Components mode

upgrade_nextjs_16

Guide through upgrade to Next.js 16

Prompts (2)

Prompt Purpose

upgrade-nextjs-16

Complete upgrade guide including codemod execution and manual fixes

enable-cache-components

Complete Cache Components setup with automated error fixing

Resources (17)

Cache Components (13):

• cache-components://overview

• Critical errors AI agents make, quick reference

• cache-components://core-mechanics

• Fundamental paradigm shift and cacheComponents behavior

• cache-components://public-caches

• Public cache mechanics using 'use cache'

• cache-components://private-caches

• Private cache mechanics using 'use cache: private'

• cache-components://runtime-prefetching

• Prefetch configuration and stale time rules

• cache-components://request-apis

• Async params, searchParams, cookies(), headers() patterns

• cache-components://cache-invalidation

• updateTag(), revalidateTag() patterns and strategies

• cache-components://advanced-patterns

• cacheLife(), cacheTag(), draft mode

• cache-components://build-behavior

• Prerendering, static shells, build-time behavior

• cache-components://error-patterns

• Common errors and solutions

• cache-components://test-patterns

• Real test-driven patterns from 125+ fixtures

• cache-components://reference

• Mental models, API reference, checklists

• cache-components://route-handlers

• Using 'use cache' in Route Handlers (API Routes)

Other (4):

• nextjs-fundamentals://use-client

• Learn when and why to use 'use client' in Server Components

• nextjs16://migration/beta-to-stable

• Complete guide for migrating from Next.js 16 beta to stable

• nextjs16://migration/examples

• Real-world examples of migrating to Next.js 16

• nextjs-docs://llms-index

• Complete Next.js documentation index

Session Initialization

Call init at the start of every session to establish documentation-first behavior and tool usage guidance.

Quick Start

Next.js 16+ (runtime diagnostics):

• Start the dev server: npm run dev (or pnpm dev )

• Call init to initialize MCP context

• Call nextjs_index to discover the running server and available tools

• Call nextjs_call with the desired toolName to execute tools on the dev server

All Next.js versions (automation and docs):

After init , use upgrade_nextjs_16 , enable_cache_components , nextjs_docs , or browser_eval as needed.

Common Workflows

Before implementing changes: Call nextjs_index to understand current application state, then nextjs_call with the appropriate tool.

Error detection: Call nextjs_index , then nextjs_call with toolName="get_errors" .

Route inspection: Call nextjs_index , then nextjs_call with toolName="get_routes" .

Server Action tracing: Call nextjs_call with toolName="get_server_action_by_id" and appropriate args.

Documentation search: Read the nextjs-docs://llms-index MCP resource to get the correct path, then call nextjs_docs with that path.

Important: The args parameter for nextjs_call MUST be an object. Omit args entirely if the tool takes no arguments.

Troubleshooting

MCP server not connecting:

• Verify Next.js v16+

• Confirm next-devtools-mcp is configured in .mcp.json

• Start or restart the dev server (npm run dev )

• If nextjs_index auto-discovery fails, ask the user which port their dev server is running on and pass it as the port parameter

"No server info found": Dev server must be running. Use the upgrade_nextjs_16 tool if on Next.js 15 or earlier.

Module not found: Clear the npx cache and restart the MCP client.

Best Practices

• Call init at session start before using other tools

• Start the dev server before using nextjs_index or nextjs_call

• Prefer nextjs_index /nextjs_call over browser_eval for error detection and diagnostics

• Use browser_eval only for tasks requiring actual page rendering or JavaScript execution

• Read nextjs-docs://llms-index resource first before calling nextjs_docs