AI Agentscoding-agentsmcpmcp-servernext-devtoolsnextjs
Installation
# Add to your Claude Code skills
git clone https://github.com/vercel/next-devtools-mcp
README.md
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.
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.
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
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
