next-devtools-mcp

The server collects anonymous usage telemetry (tool usage, error events, and session metadata). To opt out, set the NEXT_TELEMETRY_DISABLED environment variable to 1 in your shell configuration (e.g., ~/.zshrc or ~/.bashrc).

To delete existing local telemetry data, remove the directory ~/.next-devtools-mcp/.

export NEXT_TELEMETRY_DISABLED=1

You can install next-devtools-mcp for all your coding agents using the add-mcp utility. Use the -y flag to skip prompts and install to all detected agents, or the -g flag to install globally across all projects.

Alternatively, you can manually add the configuration to your MCP client's settings file.

npx add-mcp next-devtools-mcp@latest

To use the MCP server, ensure you have a Next.js 16+ dev server running. The server automatically discovers the running instance via its /_next/mcp endpoint.

1. Start your Next.js dev server:

   npm run dev

2. Ask your agent questions about the running application, such as:
   • "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?"

If your MCP client requires manual configuration, use the following JSON structure:

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

The server implements the Model Context Protocol (MCP) using StdioServerTransport. It exposes its capabilities through two primary request handlers:

1. ListTools: Returns a list of available tools, including their name, description, and an inputSchema (converted from Zod to JSON Schema) that defines the expected arguments.
2. CallTool: Executes a specific tool by name. The server validates the provided arguments against the tool's Zod schema. If valid, it invokes the tool's handler and returns the result as a text content block.

If a tool is called, the server also tracks usage via internal telemetry (event queuing) before executing the logic.

Common issues and solutions:

• ERR_MODULE_NOT_FOUND referencing next-devtools-mcp/dist: Clear your npx cache and restart your MCP client to force a fresh installation.
• [error] No server info found: This indicates nextjs_index or nextjs_call cannot find a running server. Ensure:
  1. A Next.js 16+ dev server is running (npm run dev).
  2. The server has the /_next/mcp endpoint enabled (default in Next.js 16+).
  3. The server started without errors.

The nextjs_docs tool helps agents find the correct documentation for the currently installed Next.js version. Instead of fetching docs over the network, it returns the local path to the markdown files bundled in node_modules/next/dist/docs/.

Input Parameters:

• topic (optional)
• project_path (optional, defaults to current working directory)

The nextjs_call tool invokes a specific runtime tool on a discovered server. You must run nextjs_index first to identify the correct port and toolName.

Input Parameters:

• port (required): The dev server port.
• toolName (required): The name of the runtime tool to invoke.
• args (optional): An arguments object required by specific tools.

{ "port": 3000, "toolName": "get_errors" }

The nextjs_index tool scans common ports for running Next.js 16+ dev servers. It returns a JSON list of discovered servers including their port, PID, and URL, along with the runtime tools they expose at /_next/mcp.

Exposed Runtime Tools (varies by version):

• get_errors: current build, runtime, and type errors
• get_logs: path to the dev log file
• get_page_metadata: routes, pages, component metadata
• get_project_metadata: project structure, config, dev server URL
• get_server_action_by_id: resolve a Server Action ID to its source file

The browser_eval tool acts as a gateway to the agent-browser CLI. It does not drive the browser itself; instead, it detects if agent-browser is installed and returns the necessary entry point or installation steps so the agent can run the CLI directly.

Input Parameters:

• task (optional): Used to tailor the guidance provided.