vercel/next-devtools-mcp

npm next-devtools-mcp package

next-devtools-mcp is a Model Context Protocol (MCP) server that connects coding agents like Claude and Cursor to your running Next.js dev server.

It is a thin connector. It discovers running Next.js 16+ dev servers and proxies their built-in MCP endpoint (/_next/mcp) so agents get live runtime errors, routes, and logs. It also ships two gateways that point agents at tools they run directly: version-accurate docs and the agent-browser CLI.

[!NOTE] Docs and migration workflows no longer live in this server. Next.js bundles its own docs at node_modules/next/dist/docs/, and upgrade / Cache Components workflows are distributed as agent skills. See Migrating from 0.3.x.

Requirements

• Node.js v20.19 or a newer LTS version
• npm or pnpm
• Next.js 16+ with a running dev server (for nextjs_index / nextjs_call)

Install

Install for all your coding agents with add-mcp:

npx add-mcp next-devtools-mcp@latest

Add -y to skip the prompt and install to all detected agents. Add -g to install globally across all projects.

Or add the config to your MCP client manually:

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

[!NOTE] next-devtools-mcp@latest keeps your client on the latest version.

Client-specific setup

amp mcp add next-devtools -- npx next-devtools-mcp@latest

claude mcp add next-devtools npx next-devtools-mcp@latest

codex mcp add next-devtools -- npx next-devtools-mcp@latest

env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

# Project
gemini mcp add next-devtools npx next-devtools-mcp@latest

# Global
gemini mcp add -s user next-devtools npx next-devtools-mcp@latest

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

code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'

Quick Start

Start your Next.js dev server:

npm run dev

Next.js 16+ enables its MCP endpoint by default at http://localhost:3000/_next/mcp. next-devtools-mcp discovers and connects to it automatically — no config needed.

Then ask your agent about the running app:

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?

The agent calls nextjs_index to discover servers, then nextjs_call to query their real state.

Tools

The gateways do not do the work themselves — they tell the agent where the docs are or how to install/run the CLI, and the agent runs it directly (faster than proxying through MCP).

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

Migrating from 0.3.x

Starting in 0.4.0, next-devtools-mcp is a thin connector.

Changed:

• nextjs_docs no longer fetches docs over the network. It points the agent at the docs Next.js bundles at node_modules/next/dist/docs/ (or recommends upgrading). The nextjs-docs://llms-index resource is removed.

Removed:

• init tool — it only enforced the old docs-fetch workflow.
• upgrade_nextjs_16 and enable_cache_components tools and their prompts — now distributed as agent skills.
• All cache-components://, nextjs16://, and nextjs-fundamentals:// resources — superseded by the bundled docs.

What remains: nextjs_index, nextjs_call, nextjs_docs, and browser_eval.

Privacy & Telemetry

next-devtools-mcp collects anonymous usage telemetry to improve the tool:

• Tool usage — which MCP tools are invoked (e.g. nextjs_index, nextjs_call)
• Error events — anonymous error messages when tools fail
• Session metadata — session ID, timestamps, basic environment (OS, Node.js version)

Not collected: your code, file contents or paths, personal data, credentials, or tool arguments (only tool names).

Local files live under ~/.next-devtools-mcp/ (anonymous telemetry-id, telemetry-salt, and a debug log mcp.log).

Opt out by setting the environment variable (add it to ~/.zshrc / ~/.bashrc to persist):

export NEXT_TELEMETRY_DISABLED=1

Delete local telemetry data anytime:

rm -rf ~/.next-devtools-mcp

Troubleshooting

ERR_MODULE_NOT_FOUND referencing next-devtools-mcp/dist — clear your npx cache and restart your MCP client. The server reinstalls fresh.

[error] No server info found — nextjs_index / nextjs_call need a running Next.js 16+ dev server:

1. Start it: npm run dev
2. Confirm Next.js 16+ (the /_next/mcp endpoint only exists there)
3. Verify it started without errors

browser_eval and nextjs_docs work without a dev server.

Local Development

git clone https://github.com/vercel/next-devtools-mcp.git
cd next-devtools-mcp
pnpm install
pnpm build

Point your MCP client at the local build:

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

Or with Codex:

codex mcp add next-devtools-local -- node dist/index.js

See the Next.js MCP documentation for how MCP works with Next.js and coding agents.

License

MIT