Next.js DevTools MCP

1# Next.js DevTools MCP
2 
3[![npm next-devtools-mcp package](https://img.shields.io/npm/v/next-devtools-mcp.svg)](https://npmjs.org/package/next-devtools-mcp)
4 
5`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.
6 
7 
8## Getting Started
9 
10### Requirements
11 
12- [Node.js](https://nodejs.org/) v20.19 or a newer [latest maintenance LTS](https://github.com/nodejs/Release#release-schedule) version
13- [npm](https://www.npmjs.com/) or [pnpm](https://pnpm.io/)
14 
15 
16### Install with add-mcp
17 
18Install the MCP server for all your coding agents:
19 
20```bash
21npx add-mcp next-devtools-mcp@latest
22```
23 
24Add `-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.
25 
26 
27### Manual installation
28 
29Add the following config to your MCP client:
30 
31```json
32{
33  "mcpServers": {
34    "next-devtools": {
35      "command": "npx",
36      "args": ["-y", "next-devtools-mcp@latest"]
37    }
38  }
39}
40```
41 
42> [!NOTE]
43> Using `next-devtools-mcp@latest` ensures that your MCP client will always use the latest version of the Next.js DevTools MCP server.
44 
45### MCP Client Configuration
46 
47<details>
48<summary>Amp</summary>
49 
50**Using Amp CLI:**
51 
52```bash
53amp mcp add next-devtools -- npx next-devtools-mcp@latest
54```
55 
56**Or configure manually:**
57 
58Follow [Amp's MCP documentation](https://ampcode.com/manual#mcp) and apply the standard configuration shown above.
59 
60</details>
61 
62<details>
63<summary>Claude Code</summary>
64 
65Use the Claude Code CLI to add the Next.js DevTools MCP server:
66 
67```bash
68claude mcp add next-devtools npx next-devtools-mcp@latest
69```
70 
71Alternatively, manually configure Claude by editing your MCP settings file and adding the configuration shown above.
72 
73</details>
74 
75<details>
76<summary>Codex</summary>
77 
78**Using Codex CLI:**
79 
80```bash
81codex mcp add next-devtools -- npx next-devtools-mcp@latest
82```
83 
84**Or configure manually:**
85 
86Follow the MCP setup guide with the standard configuration format:
87- Command: `npx`
88- Arguments: `-y, next-devtools-mcp@latest`
89 
90**Windows 11 Special Configuration:**
91 
92Update `.codex/config.toml` with environment variables and increased startup timeout:
93 
94```toml
95env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
96startup_timeout_ms = 20_000
97```
98 
99</details>
100 
101<details>
102<summary>Cursor</summary>
103 
104**Click the button to install:**
105 
106[Install in Cursor](https://cursor.com/en/install-mcp?name=next-devtools&config=eyJjb21tYW5kIjoibnB4IC15IG5leHQtZGV2dG9vbHMtbWNwQGxhdGVzdCJ9)
107 
108**Or install manually:**
109 
110Go to `Cursor Settings` → `MCP` → `New MCP Server`. Use the config provided above.
111 
112</details>
113 
114<details>
115<summary>Gemini</summary>
116 
117**Using Gemini CLI:**
118 
119Project-wide installation:
120```bash
121gemini mcp add next-devtools npx next-devtools-mcp@latest
122```
123 
124Global installation:
125```bash
126gemini mcp add -s user next-devtools npx next-devtools-mcp@latest
127```
128 
129**Or configure manually:**
130 
131Follow the MCP setup guide with these parameters:
132- Command: `npx`
133- Arguments: `-y, next-devtools-mcp@latest`
134 
135</details>
136 
137<details>
138<summary>Google Antigravity</summary>
139 
140**Configure in MCP config file:**
141 
142Add this to your Antigravity MCP config file: `.gemini/antigravity/mcp_config.json`
143 
144```json
145{
146  "mcpServers": {
147    "next-devtools": {
148      "command": "npx",
149      "args": ["-y", "next-devtools-mcp@latest"]
150    }
151  }
152}
153```
154 
155See [Antigravity MCP docs](https://antigravity.google/docs/mcp) for more info.
156 
157</details>
158 
159<details>
160<summary>VS Code / Copilot</summary>
161 
162**Using VS Code CLI:**
163 
164```bash
165code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'
166```
167 
168**Or configure manually:**
169 
170Follow the official VS Code MCP server setup guide and add the Next.js DevTools server through VS Code settings.
171 
172</details>
173 
174<details>
175<summary>Warp</summary>
176 
177**Using Warp UI:**
178 
179Navigate to `Settings | AI | Manage MCP Servers` and select `+ Add` to register a new MCP server with the following configuration:
180- Name: `next-devtools`
181- Command: `npx`
182- Arguments: `-y, next-devtools-mcp@latest`
183 
184</details>
185 
186## Quick Start
187 
188### For Next.js 16+ Projects (Recommended)
189 
190To unlock the full power of runtime diagnostics, start your Next.js dev server:
191 
192```bash
193npm run dev
194```
195 
196Next.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.
197 
198**⚠️ IMPORTANT: Start every Next.js session by calling the `init` tool to set up proper context:**
199 
200```
201Use the init tool to set up Next.js DevTools context
202```
203 
204This initializes the MCP context and ensures the AI assistant uses official Next.js documentation for all queries.
205 
206**After initialization, try these prompts to explore runtime diagnostics:**
207 
208```
209Next Devtools, what errors are in my Next.js application?
210```
211 
212```
213Next Devtools, show me the structure of my routes
214```
215 
216```
217Next Devtools, what's in the development server logs?
218```
219 
220Your coding agent will use the `nextjs_index` and `nextjs_call` tools to query your running application's actual state.
221 
222### For All Next.js Projects
223 
224You can use the development automation and documentation tools regardless of Next.js version:
225 
226```
227Next Devtools, help me upgrade my Next.js app to version 16
228```
229 
230```
231Next Devtools, enable Cache Components in my Next.js app
232```
233 
234```
235Next Devtools, search Next.js docs for generateMetadata
236```
237 
238### 💡 Pro Tip: Auto-Initialize on Every Session
239 
240To 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:
241 
242<details>
243<summary>Claude Code / Claude Desktop</summary>
244 
245Add to `~/.claude/CLAUDE.md` (global) or `./.claude/CLAUDE.md` (project-specific):
246 
247```markdown
248**When starting work on a Next.js project, ALWAYS call the `init` tool from
249next-devtools-mcp FIRST to set up proper context and establish documentation
250requirements. Do this automatically without being asked.**
251```
252 
253</details>
254 
255<details>
256<summary>Cursor</summary>
257 
258Add to `.cursorrules` in your project root or global Cursor settings:
259 
260```
261When working with Next.js, always call the init tool from next-devtools-mcp
262at the start of the session to establish proper context and documentation requirements.
263```
264 
265</details>
266 
267<details>
268<summary>Codex / Other AI Coding Assistants</summary>
269 
270Add to your agent's configuration file (e.g., `.codex/instructions.md`, `agent.md`, or similar):
271 
272```markdown
273**Next.js Initialization**: When starting work on a Next.js project, automatically
274call the `init` tool from the next-devtools-mcp server FIRST. This establishes
275proper context and ensures all Next.js queries use official documentation.
276```
277 
278</details>
279 
280**Why this matters:**
281- ✅ Ensures consistent context across all Next.js work
282- ✅ Automatically establishes the documentation-first requirement
283- ✅ No need to manually call init every time
284- ✅ Works across all your Next.js projects
285 
286## MCP Resources
287 
288The knowledge base resources are automatically available to your coding agent and are split into focused sections for efficient context management. Current resource URIs:
289 
290<details>
291<summary>📚 Available Knowledge Base Resources (click to expand)</summary>
292 
293- Cache Components (12 sections):
294  - `cache-components://overview`
295  - `cache-components://core-mechanics`
296  - `cache-components://public-caches`
297  - `cache-components://private-caches`
298  - `cache-components://runtime-prefetching`
299  - `cache-components://request-apis`
300  - `cache-components://cache-invalidation`
301  - `cache-components://advanced-patterns`
302  - `cache-components://build-behavior`
303  - `cache-components://error-patterns`
304  - `cache-components://test-patterns`
305  - `cache-components://reference`
306 
307- Next.js 16 migration:
308  - `nextjs16://migration/beta-to-stable`
309  - `nextjs16://migration/examples`
310 
311- Next.js fundamentals:
312  - `nextjs-fundamentals://use-client`
313 
314</details>
315 
316Resources are loaded on-demand by your coding agent, providing targeted knowledge without overwhelming the context window.
317 
318## MCP Prompts
319 
320Pre-configured prompts to help with common Next.js development tasks:
321 
322<details>
323<summary>💡 Available Prompts (click to expand)</summary>
324 
325- **`upgrade-nextjs-16`** - Guide for upgrading to Next.js 16
326- **`enable-cache-components`** - Migrate and enable Cache Components mode for Next.js 16
327 
328</details>
329 
330## MCP Tools
331 
332<details>
333<summary><code>init</code></summary>
334 
335Initialize Next.js DevTools MCP context and establish documentation requirements.
336 
337**Capabilities:**
338- Sets up proper context for AI assistants working with Next.js
339- Establishes requirement to use `nextjs_docs` for ALL Next.js-related queries
340- Documents all available MCP tools and their use cases
341- Provides best practices for Next.js development with MCP
342- Includes example workflows and quick start checklist
343 
344**When to use:**
345- At the beginning of a Next.js development session
346- To understand available tools and establish proper context
347- To ensure documentation-first approach for Next.js development
348 
349**Input:**
350- `project_path` (optional) - Path to Next.js project (defaults to current directory)
351 
352**Output:**
353- Comprehensive initialization context and guidance for Next.js development with MCP tools
354 
355</details>
356 
357<details>
358<summary><code>nextjs_docs</code></summary>
359 
360Search and retrieve Next.js official documentation and knowledge base.
361 
362**Capabilities:**
363- Two-step process: 1) Search for docs by keyword to get paths, 2) Fetch full markdown content by path
364- Uses official Next.js documentation search API
365- Provides access to comprehensive Next.js guides, API references, and best practices
366- Supports filtering by router type (App Router, Pages Router, or both)
367 
368**Input:**
369- `action` (required) - Action to perform: `search` to find docs, `get` to fetch full content
370- `query` (optional) - Required for `search`. Keyword search query (e.g., 'metadata', 'generateStaticParams', 'middleware')
371- `path` (optional) - Required for `get`. Doc path from search results (e.g., '/docs/app/api-reference/functions/refresh')
372- `anchor` (optional) - Optional for `get`. Anchor/section from search results (e.g., 'usage')
373- `routerType` (optional) - For `search` only. Filter by: `app`, `pages`, or `all` (default: `all`)
374 
375**Output:**
376- Search results with doc titles, paths, content snippets, sections, and anchors
377- Full markdown content for specific documentation pages
378 
379</details>
380 
381<details>
382<summary><code>browser_eval</code></summary>
383 
384Automate and test web applications using Playwright browser automation.
385 
386**When to use:**
387- Verifying pages in Next.js projects (especially during upgrades or testing)
388- Testing user interactions and flows
389- Taking screenshots for visual verification
390- Detecting runtime errors, hydration issues, and client-side problems
391- Capturing browser console errors and warnings
392 
393**Important:** For Next.js projects, prioritize using the `nextjs_index` and `nextjs_call` tools instead of browser console log forwarding. Only use browser_eval's `console_messages` action as a fallback when these tools are not available.
394 
395**Available actions:**
396- `start` - Start browser automation (automatically installs if needed)
397- `navigate` - Navigate to a URL
398- `click` - Click on an element
399- `type` - Type text into an element
400- `fill_form` - Fill multiple form fields at once
401- `evaluate` - Execute JavaScript in browser context
402- `screenshot` - Take a screenshot of the page
403- `console_messages` - Get browser console messages
404- `close` - Close the browser
405- `drag` - Perform drag and drop
406- `upload_file` - Upload files
407- `list_tools` - List all available browser automation tools from the server
408 
409**Input:**
410- `action` (required) - The action to perform
411- `browser` (optional) - Browser to use: `chrome`, `firefox`, `webkit`, `msedge` (default: `chrome`)
412- `headless` (optional) - Run browser in headless mode (default: `true`)
413- Action-specific parameters (see tool description for details)
414 
415**Output:**
416- JSON with action result, screenshots (base64), console messages, or error information
417 
418</details>
419 
420<details>
421<summary><code>nextjs_index</code></summary>
422 
423Discover all running Next.js dev servers and list their available MCP tools.
424 
425**What this tool does:**
426 
427Automatically discovers all running Next.js 16+ dev servers on your machine and lists the runtime diagnostic tools available from each server's built-in MCP endpoint at `/_next/mcp`.
428 
429**No parameters required** - Just call the tool and it will scan for servers.
430 
431**Available Next.js Runtime Tools** (varies by Next.js version):
432- `get_errors` - Get current build, runtime, and type errors
433- `get_logs` - Get path to development log file (browser console + server output)
434- `get_page_metadata` - Query application routes, pages, and component metadata
435- `get_project_metadata` - Get project structure, config, and dev server URL
436- `get_server_action_by_id` - Look up Server Actions by ID to find source files
437 
438**Requirements:**
439- Next.js 16+ (MCP enabled by default)
440- Running dev server (`npm run dev`)
441 
442**Output:**
443- JSON with list of discovered servers, each containing:
444  - Port, PID, URL
445  - Available tools with descriptions and input schemas
446 
447**Example prompts:**
448- "Next Devtools, what servers are running?"
449- "Next Devtools, show me available diagnostic tools"
450 
451</details>
452 
453<details>
454<summary><code>nextjs_call</code></summary>
455 
456Execute a specific MCP tool on a running Next.js dev server.
457 
458**What this tool does:**
459 
460Calls a specific runtime diagnostic tool on a Next.js 16+ dev server's built-in MCP endpoint at `/_next/mcp`.
461 
462**Input Parameters:**
463- `port` (required) - Dev server port (use `nextjs_index` first to discover)
464- `toolName` (required) - Name of the Next.js tool to invoke
465- `args` (optional) - Arguments object for the tool (only if required by that tool)
466 
467**Requirements:**
468- Next.js 16+ (MCP enabled by default)
469- Running dev server (`npm run dev`)
470- Use `nextjs_index` first to discover available servers and tools
471 
472**Typical workflow:**
473 
474```javascript
475// Step 1: Discover servers and tools
476// (call nextjs_index first)
477 
478// Step 2: Call a specific tool
479{
480  "port": 3000,
481  "toolName": "get_errors"
482  // args is optional and only needed if the tool requires parameters
483}
484```
485 
486**Output:**
487- JSON with tool execution results
488 
489**Example prompts that use this tool:**
490- "Next Devtools, what errors are in my Next.js app?"
491- "Next Devtools, show me my application routes"
492- "Next Devtools, what's in the dev server logs?"
493- "Next Devtools, find the Server Action with ID xyz"
494 
495</details>
496 
497<details>
498<summary><code>upgrade_nextjs_16</code></summary>
499 
500Guides through upgrading Next.js to version 16 with automated codemod execution.
501 
502**Capabilities:**
503- Runs official Next.js codemod automatically (requires clean git state)
504- Handles async API changes (params, searchParams, cookies, headers)
505- Migrates configuration changes
506- Updates image defaults and optimization
507- Fixes parallel routes and dynamic segments
508- Handles deprecated API removals
509- Provides guidance for React 19 compatibility
510 
511**Input:**
512- `project_path` (optional) - Path to Next.js project (defaults to current directory)
513 
514**Output:**
515- Structured JSON with step-by-step upgrade guidance
516 
517</details>
518 
519<details>
520<summary><code>enable_cache_components</code></summary>
521 
522Complete Cache Components setup, enablement, and migration for Next.js 16 with automated error detection and fixing. This tool is used for migrating Next.js applications to Cache Components mode.
523 
524**Capabilities:**
525- Pre-flight checks (package manager, Next.js version, configuration)
526- Enable Cache Components configuration
527- Start dev server with MCP enabled
528- Automated route verification and error detection
529- Automated error fixing with intelligent boundary setup (Suspense, caching directives, static params)
530- Final verification and build testing
531 
532**Input:**
533- `project_path` (optional) - Path to Next.js project (defaults to current directory)
534 
535**Output:**
536- Structured JSON with complete setup guidance and phase-by-phase instructions
537 
538**Example Usage:**
539 
540With Claude Code:
541```
542Next Devtools, help me enable Cache Components in my Next.js 16 app
543```
544 
545With other agents or programmatically:
546```json
547{
548  "tool": "enable_cache_components",
549  "args": {
550    "project_path": "/path/to/project"
551  }
552}
553```
554 
555</details>
556 
557## Privacy & Telemetry
558 
559### What Data is Collected
560 
561`next-devtools-mcp` collects anonymous usage telemetry to help improve the tool. The following data is collected:
562 
563- **Tool usage**: Which MCP tools are invoked (e.g., `nextjs_index`, `nextjs_call`, `browser_eval`, `upgrade_nextjs_16`)
564- **Error events**: Anonymous error messages when tools fail
565- **Session metadata**: Session ID, timestamps, and basic environment info (OS, Node.js version)
566 
567**What is NOT collected:**
568- Your project code, file contents, or file paths
569- Personal information or identifiable data
570- API keys, credentials, or sensitive configuration
571- Arguments passed to tools (except tool names)
572 
573Local files are written under `~/.next-devtools-mcp/` (anonymous `telemetry-id`, `telemetry-salt`, and a debug log `mcp.log`). Events are sent to the telemetry endpoint in the background to help us understand usage patterns and improve reliability.
574 
575### Opt-Out
576 
577To disable telemetry completely, set the environment variable:
578 
579```bash
580export NEXT_TELEMETRY_DISABLED=1
581```
582 
583Add this to your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`) to make it permanent.
584 
585You can also delete your local telemetry data at any time:
586 
587```bash
588rm -rf ~/.next-devtools-mcp
589```
590 
591## Troubleshooting
592 
593### Module Not Found Error
594 
595If you encounter an error like:
596 
597```
598Error [ERR_MODULE_NOT_FOUND]: Cannot find module '...\next-devtools-mcp\dist\resources\(cache-components)\...'
599```
600 
601**Solution:** Clear your npx cache and restart your MCP client (Cursor, Claude Code, etc.). The server will be freshly installed.
602 
603### "No server info found" Error
604 
605If you see `[error] No server info found`:
606 
607**Solutions:**
6081. Make sure your Next.js dev server is running: `npm run dev`
6092. If using Next.js 15 or earlier, use the `upgrade_nextjs_16` tool to upgrade to Next.js 16+
6103. Verify your dev server started successfully without errors
611 
612**Note:** The `nextjs_index` and `nextjs_call` tools require Next.js 16+ with a running dev server. Other tools (`nextjs_docs`, `browser_eval`, `upgrade_nextjs_16`, `enable_cache_components`) work without a running server.
613 
614## Local Development
615 
616To run the MCP server locally for development:
617 
6181. Clone the repository
6192. Install dependencies:
620   ```bash
621   pnpm install
622   pnpm build
623   ```
6243. Configure your MCP client to use the local version:
625   ```json
626   {
627     "mcpServers": {
628       "next-devtools": {
629         "command": "node",
630         "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"]
631       }
632     }
633   }
634   ```
635 
636   Note: Replace `/absolute/path/to/next-devtools-mcp` with the actual absolute path to your cloned repository.
637 
638   or manually add, e.g. with codex:
639   ```
640   codex mcp add next-devtools-local -- node dist/index.js
641   ```
642 
643## Features
644 
645This MCP server provides coding agents with comprehensive Next.js development capabilities through three primary mechanisms:
646 
647### **1. Runtime Diagnostics & Live State Access** (Next.js 16+)
648Connect directly to your running Next.js dev server's built-in MCP endpoint to query:
649- Real-time build and runtime errors
650- Application routes, pages, and component metadata
651- Development server logs and diagnostics
652- Server Actions and component hierarchies
653 
654### **2. Development Automation**
655Tools for common Next.js workflows:
656- **Automated Next.js 16 upgrades** with official codemods
657- **Cache Components migration and setup** with error detection and automated fixes
658- **Browser testing integration** via Playwright for visual verification
659 
660### **3. Knowledge Base & Documentation**
661- Curated Next.js 16 knowledge base (12 focused resources on Cache Components, async APIs, etc.)
662- Direct access to official Next.js documentation via search API
663- Pre-configured prompts for upgrade guidance and Cache Components enablement
664 
665> **Learn more:** See the [Next.js MCP documentation](https://nextjs.org/docs/app/guides/mcp) for details on how MCP servers work with Next.js and coding agents.
666 
667## How It Works
668 
669This package provides a **bridge MCP server** that connects your coding agent to Next.js development tools:
670 
671```
672Coding Agent
673      ↓
674  next-devtools-mcp (this package)
675      ↓
676      ├─→ Next.js Dev Server MCP Endpoint (/_next/mcp) ← Runtime diagnostics
677      ├─→ Playwright MCP Server ← Browser automation
678      └─→ Knowledge Base & Tools ← Documentation, upgrades, setup automation
679```
680 
681**Key Architecture Points:**
682 
6831. **For Next.js 16+ projects**: This server automatically discovers and connects to your running Next.js dev server's built-in MCP endpoint at `http://localhost:PORT/_next/mcp`. This gives coding agents direct access to runtime errors, routes, logs, and application state.
684 
6852. **For all Next.js projects**: Provides development automation tools (upgrades, Cache Components setup), documentation access, and browser testing capabilities that work independently of the runtime connection.
686 
6873. **Simple workflow**: Call `nextjs_index` to see all servers and available tools, then call `nextjs_call` with the specific port and tool name you want to execute.
688 
689 
690## License
691 
692MIT License
693