Next.js DevTools

The Next.js DevTools MCP server connects your coding agents to Next.js runtime diagnostics, automates common workflows, and provides direct access to official Next.js documentation. It helps you observe errors, inspect routes and metadata, run upgrades, and set up Cache Components, all from a unified MCP endpoint.

How to use

You interact with the Next.js DevTools MCP through your MCP client. Start a Next.js dev server for 16+ projects to enable runtime diagnostics at the built-in MCP endpoint. Use the available MCP tools to discover running servers, inspect errors and logs, query routes and metadata, and perform automated tasks such as upgrades and Cache Components setup. Begin by discovering available servers and then invoke the specific tool you need, providing any required parameters.

How to install

Prerequisites: Make sure you have Node.js v20.19 or newer, and either npm or pnpm installed.

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

Additional setup and options

If you prefer a local development setup, you can run the MCP server directly with Node. Use the command path to the built distribution as shown in the local development steps.

{
  "mcpServers": {
    "next-devtools-local": {
      "command": "node",
      "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"]
    }
  }
}

Notes on initialization and usage

To ensure your AI assistant uses official Next.js documentation for all Next.js queries, initialize the MCP context at the start of each session with the dedicated init tool. After initialization, you can explore runtime diagnostics, project structure, and server logs using prompts that reference the available MCP tools.

Troubleshooting and tips

If you encounter module or server information errors, try restarting the MCP client after clearing relevant caches. Ensure your Next.js dev server is running when using runtime tools that require an active server. For environments without a running server, you can still use the automation and documentation tools to manage upgrades and configuration.

Security and telemetry considerations

Telemetry is collected in anonymous form to improve the MCP experience. You can opt out by setting a specific environment variable in your shell configuration.

Local development and building

To run the MCP server locally for development, install dependencies, build, then start using the stdio command shown in your local configuration. The process mirrors standard Node-based projects and does not require modifying your application code.

Available tools

init

Initialize Next.js DevTools MCP context, establishing documentation-first behavior and guiding tool usage at the start of a session.

nextjs_docs

Search and fetch official Next.js documentation and knowledge base to answer queries with up-to-date guidance.

browser_eval

Automate browser tasks for verification and testing using Playwright with guidance to prefer Next.js-native tooling when available.

nextjs_index

Discover all running Next.js 16+ dev servers and list their available MCP tools along with endpoints.

nextjs_call

Execute a specific MCP tool on a running Next.js dev server via its built-in MCP endpoint.

upgrade_nextjs_16

Guide and automate the upgrade process to Next.js 16, including codemods and compatibility adjustments.

enable_cache_components

Complete setup and migration to Cache Components mode with automated checks and fixes for Next.js 16.