Registry / web-framework / next-devtools-mcp

next-devtools-mcp

library0.3.10jsnpmunverified

Next.js DevTools MCP (Model Context Protocol) is a server-side component designed to extend Next.js development environments with AI agent capabilities. It provides a standardized interface for coding agents like Claude or Cursor to interact with and introspect running Next.js applications, enabling advanced features such as runtime diagnostics, code generation, and debugging assistance. The current stable version is `0.3.10`, with frequent patch releases indicating active development and a focus on stability, security, and incremental improvements. Key differentiators include its tight integration with the Next.js ecosystem, leveraging its internal mechanisms for deep introspection, and its adherence to the Model Context Protocol, making it compatible with a growing number of AI developer tools. It acts as a crucial bridge, allowing AI agents to understand the context of a Next.js project and provide highly relevant assistance, offering capabilities like automated upgrades, Cache Component setup, and access to documentation.

web-framework devops observability

npm install next-devtools-mcp

github ↗package ↗

INSTALL

IMPORT

SIG · NEXT-DEVTOOLS-MCP

next-devtools-mcp

web-frameworkjavascriptv0.3.10

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Next.js DevTools Server CLI Invocation

✓ npx -y next-devtools-mcp@latest

✗ import { NextDevToolsMcp } from 'next-devtools-mcp';

This package is primarily a CLI server, not a library for direct JavaScript/TypeScript symbol imports. Its functionality is 'imported' into a development environment by executing it via `npx` (or a global/local installation). The `@latest` tag ensures you always run the most recent version, which is recommended due to frequent updates and security fixes.

Programmatic Invocation via Child Process

✓ import { spawn } from 'child_process'; const mcpProcess = spawn('npx', ['-y', 'next-devtools-mcp@latest'], { stdio: ['inherit', 'inherit', 'inherit'], shell: true }); mcpProcess.on('error', (err) => console.error('Failed to start MCP server:', err)); mcpProcess.on('exit', (code) => console.log(`MCP server exited with code ${code}`));

✗ require('next-devtools-mcp').start();

While not a typical library import, developers might programmatically interact with the server by spawning it as a child process, for example, within a custom development script or CI/CD environment. This example demonstrates a basic `child_process.spawn` usage to execute the `npx` command. This package's `package.json` specifies `type: module` and exports `./dist/index.js` as the main entry point, but direct programmatic `require` or `import` of internal server logic is not the intended or stable public API.

MCP Client Configuration (conceptual 'import')

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

✗ const NextDevTools = new NextDevToolsMCP();

For AI coding agents (MCP clients) to 'import' or utilize the Next.js DevTools MCP server, they need to be configured with the command to run the server. This JSON snippet illustrates the typical configuration structure used by various MCP clients (e.g., Cursor, Gemini, Claude Code, VS Code). This configuration tells the client how to launch and connect to the `next-devtools-mcp` server.

Demonstrates how to set up and run a Next.js 16+ project, and then configure an AI agent to connect to the `next-devtools-mcp` server for enhanced development capabilities and runtime diagnostics.

{ "name": "my-next-app", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "next lint" }, "dependencies": { "react": "^19.0.0", "react-dom": "^19.0.0", "next": "^16.0.7" }, "devDependencies": { "typescript": "^5", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "eslint": "^8", "eslint-config-next": "16.0.7" } } // 1. Create a Next.js 16+ project (if you don't have one) // npx create-next-app@latest my-next-app --ts // cd my-next-app // 2. Start your Next.js development server (in a separate terminal): // npm run dev // 3. Configure your AI agent (e.g., Cursor, Claude Code, Gemini) to use the next-devtools-mcp server. // Add this to your MCP client's configuration file (e.g., .cursor/mcp.json, .mcp.json, etc.): /* { "mcpServers": { "next-devtools": { "command": "npx", "args": ["-y", "next-devtools-mcp@latest"] } } } */ // 4. Once configured, your AI agent can now use Next.js DevTools capabilities. // Example CLI command to add the server (specific to your client, e.g., for Gemini): // gemini mcp add next-devtools npx next-devtools-mcp@latest

next-devtools-mcp --version

Debug

Known issues

breakingA critical-severity vulnerability (CVE-2025-66414) was discovered in `@modelcontextprotocol/sdk` affecting versions prior to 1.24.0, involving insecure default initialization of resources. This could allow an attacker to invoke tools or access resources via DNS rebinding if an HTTP-based MCP server is running locally without authentication and DNS rebinding protection is not explicitly enabled. Note: This specific `next-devtools-mcp` server uses stdio transport, which is generally not affected by this particular DNS rebinding vulnerability, but upgrading dependencies is crucial for overall security.

fix

Upgrade `next-devtools-mcp` to version `0.3.7` or later to include the `@modelcontextprotocol/sdk` update to `1.24.3` (which includes the fix for `1.24.0`). Ensure all MCP-related dependencies are kept up-to-date.

affects: <0.3.7

breakingNext.js versions prior to 16.0.7 (and React 19) were affected by a critical remote code execution vulnerability (CVE-2025-55182) in React Server Components, also known as 'React2Shell'. Although this `next-devtools-mcp` update fixes its internal Next.js dependency, the vulnerability primarily exists in the Next.js *application* itself, requiring application-level upgrades.

fix

Upgrade `next-devtools-mcp` to version `0.3.7` or later. More critically, ensure your Next.js application is upgraded to Next.js `16.0.7` or a patched version of Next.js 15.x/16.x that addresses CVE-2025-55182. Deploy platform-level WAF rules where applicable.

affects: <0.3.7

deprecatedPrior to `v0.3.0`, the package might have referenced 'experimental MCP' implementations. These outdated experimental interfaces were removed and superseded by the official MCP TypeScript SDK.

fix

Upgrade to `next-devtools-mcp v0.3.0` or later. Migrate any client configurations or custom integrations to use the official MCP TypeScript SDK and remove references to experimental MCPs.

affects: <0.3.0

gotchaOlder versions of `next-devtools-mcp` (around `v0.3.0`) experienced issues with CommonJS (CJS) imports for internal 'find process helper' utilities, potentially leading to module resolution errors in certain environments.

fix

Upgrade `next-devtools-mcp` to version `0.3.1` or later to resolve internal CJS/ESM module resolution inconsistencies.

affects: ~0.3.0

gotchaThe server has undergone improvements in Next.js server discovery and specifically fixed issues related to server discovery within Windows Subsystem for Linux (WSL) environments, where it might have failed to connect to running Next.js instances.

fix

Upgrade `next-devtools-mcp` to version `0.3.3` or later to benefit from improved server discovery, particularly in WSL environments. Ensure your Next.js application is running (`npm run dev`) and correctly configured.

affects: <0.3.3

Errors

Common errors & fixes

Error: Agent idle caused by strict reply prohibition

An issue in earlier versions where the agent would become idle due to strict reply prohibition, preventing proper communication.

fix

Upgrade `next-devtools-mcp` to version `0.3.8` or later to fix agent idle issues caused by strict reply prohibition.

MCP Server failed to start or timed out connecting (especially on Windows)

Default startup timeouts in some MCP clients (e.g., Codex) can be too low for the `next-devtools-mcp` server, especially on Windows or under heavy system load.

fix

Increase the `startup_timeout_ms` in your MCP client's configuration. For Codex on Windows, add `env = { SystemRoot="C:\Windows", PROGRAMFILES="C:\Program Files" }` and `startup_timeout_ms = 20_000` to `.codex/config.toml`.

Next DevTools MCP server not connecting to Next.js application

Common causes include using an incompatible Next.js version, the Next.js dev server not running, or incorrect MCP client configuration.

fix

Ensure your Next.js project is version 16 or above. Verify that your Next.js development server is actively running (`npm run dev`). Confirm that `next-devtools-mcp` is correctly configured in your `.mcp.json` file or client settings and restart your development server if it was already running before connecting the MCP server.

Upgrade

Version history

0.3.10latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredCore dependency for implementing the Model Context Protocol, enabling communication with AI agents.

Next.jsrequiredThis package is specifically designed to interact with Next.js applications (v16+ recommended for full features). While not a direct NPM dependency of this package itself, a compatible Next.js project is a runtime requirement for its functionality.

Node.jsrequiredRequires Node.js v20.19 or a newer LTS version to run the server.

npm | pnpmrequiredRequired package manager to install and run the server, typically via `npx` or local installation.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vercel/next-devtools-mcp ↗

packagehttps://www.npmjs.com/package/next-devtools-mcp ↗