Next.js DevTools MCP

next-devtools-mcp is a Model Context Protocol (MCP) server that provides Next.js development tools and utilities for coding agents like Claude and Cursor.

Getting Started

Requirements

• Node.js v20.19 or a newer latest maintenance LTS version
• npm or pnpm

Install with add-mcp

Install the MCP server for all your coding agents:

npx add-mcp next-devtools-mcp@latest

Add -y to skip the confirmation prompt and install to all detected agents already in use in the project directory. Add -g to install globally across all projects.

Manual installation

Add the following config to your MCP client:

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

[!NOTE] Using next-devtools-mcp@latest ensures that your MCP client will always use the latest version of the Next.js DevTools MCP server.

MCP Client Configuration

Using Amp CLI:

amp mcp add next-devtools -- npx next-devtools-mcp@latest

Or configure manually:

Follow Amp's MCP documentation and apply the standard configuration shown above.

Use the Claude Code CLI to add the Next.js DevTools MCP server:

claude mcp add next-devtools npx next-devtools-mcp@latest

Alternatively, manually configure Claude by editing your MCP settings file and adding the configuration shown above.

Using Codex CLI:

codex mcp add next-devtools -- npx next-devtools-mcp@latest

Or configure manually:

Follow the MCP setup guide with the standard configuration format:

• Command: npx
• Arguments: -y, next-devtools-mcp@latest

Windows 11 Special Configuration:

Update .codex/config.toml with environment variables and increased startup timeout:

env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

Click the button to install:

Install in Cursor

Or install manually:

Go to Cursor Settings → MCP → New MCP Server. Use the config provided above.

Using Gemini CLI:

Project-wide installation:

gemini mcp add next-devtools npx next-devtools-mcp@latest

Global installation:

gemini mcp add -s user next-devtools npx next-devtools-mcp@latest

Or configure manually:

Follow the MCP setup guide with these parameters:

• Command: npx
• Arguments: -y, next-devtools-mcp@latest

Configure in MCP config file:

Add this to your Antigravity MCP config file: .gemini/antigravity/mcp_config.json

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

See Antigravity MCP docs for more info.

Using VS Code CLI:

code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'

Or configure manually:

Follow the official VS Code MCP server setup guide and add the Next.js DevTools server through VS Code settings.

Using Warp UI:

Navigate to Settings | AI | Manage MCP Servers and select + Add to register a new MCP server with the following configuration:

• Name: next-devtools
• Command: npx
• Arguments: -y, next-devtools-mcp@latest

Quick Start

For Next.js 16+ Projects (Recommended)

To unlock the full power of runtime diagnostics, start your Next.js dev server:

npm run dev

Next.js 16+ has MCP enabled by default at http://localhost:3000/_next/mcp (or whichever port your dev server uses). The next-devtools-mcp server will automatically discover and connect to it.

⚠️ IMPORTANT: Start every Next.js session by calling the init tool to set up proper context:

Use the init tool to set up Next.js DevTools context

This initializes the MCP context and ensures the AI assistant uses official Next.js documentation for all queries.

After initialization, try these prompts to explore runtime diagnostics:

Next Devtools, what errors are in my Next.js application?

Next Devtools, show me the structure of my routes

Next Devtools, what's in the development server logs?

Your coding agent will use the nextjs_index and nextjs_call tools to query your running application's actual state.

For All Next.js Projects

You can use the development automation and documentation tools regardless of Next.js version:

Next Devtools, help me upgrade my Next.js app to version 16

Next Devtools, enable Cache Components in my Next.js app

Next Devtools, search Next.js docs for generateMetadata

💡 Pro Tip: Auto-Initialize on Every Session

To make your AI assistant automatically call the init tool at the start of every Next.js session without being asked, add this instruction to your agent's configuration file:

Add to ~/.claude/CLAUDE.md (global) or ./.claude/CLAUDE.md (project-specific):

**When starting work on a Next.js project, ALWAYS call the `init` tool from
next-devtools-mcp FIRST to set up proper context and establish documentation
requirements. Do this automatically without being asked.**

Add to .cursorrules in your project root or global Cursor settings:

When working with Next.js, always call the init tool from next-devtools-mcp
at the start of the session to establish proper context and documentation requirements.

Add to your agent's configuration file (e.g., .codex/instructions.md, agent.md, or similar):

**Next.js Initialization**: When starting work on a Next.js project, automatically
call the `init` tool from the next-devtools-mcp server FIRST. This establishes
proper context and ensures all Next.js queries use official documentation.

Why this matters:

• ✅ Ensures consistent context across all Next.js work
• ✅ Automatically establishes the documentation-first requirement
• ✅ No need to manually call init every time
• ✅ Works across all your Next.js projects

MCP Resources

The knowledge base resources are automatically available to your coding agent and are split into focused sections for efficient context management. Current resource URIs:

• Cache Components (12 sections):

  • cache-components://overview
  • cache-components://core-mechanics
  • cache-components://public-caches
  • cache-components://private-caches
  • cache-components://runtime-prefetching
  • cache-components://request-apis
  • cache-components://cache-invalidation
  • cache-components://advanced-patterns
  • cache-components://build-behavior
  • cache-components://error-patterns
  • cache-components://test-patterns
  • cache-components://reference

• Next.js 16 migration:

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

• Next.js fundamentals:

  • nextjs-fundamentals://use-client

Resources are loaded on-demand by your coding agent, providing targeted knowledge without overwhelming the context window.

MCP Prompts

Pre-configured prompts to help with common Next.js development tasks:

• upgrade-nextjs-16 - Guide for upgrading to Next.js 16
• enable-cache-components - Migrate and enable Cache Components mode for Next.js 16

MCP Tools

Initialize Next.js DevTools MCP context and establish documentation requirements.

Capabilities:

• Sets up proper context for AI assistants working with Next.js
• Establishes requirement to use nextjs_docs for ALL Next.js-related queries
• Documents all available MCP tools and their use cases
• Provides best practices for Next.js development with MCP
• Includes example workflows and quick start checklist

When to use:

• At the beginning of a Next.js development session
• To understand available tools and establish proper context
• To ensure documentation-first approach for Next.js development

Input:

• project_path (optional) - Path to Next.js project (defaults to current directory)

Output:

• Comprehensive initialization context and guidance for Next.js development with MCP tools

Search and retrieve Next.js official documentation and knowledge base.

Capabilities:

• Two-step process: 1) Search for docs by keyword to get paths, 2) Fetch full markdown content by path
• Uses official Next.js documentation search API
• Provides access to comprehensive Next.js guides, API references, and best practices
• Supports filtering by router type (App Router, Pages Router, or both)

Input:

• action (required) - Action to perform: search to find docs, get to fetch full content
• query (optional) - Required for search. Keyword search query (e.g., 'metadata',