next-devtools-mcp

Name: next-devtools-mcp
Author: vercel

Local

github.com/vercelDeveloper Tools834Updated 6w ago

Repository

About next-devtools-mcp

next-devtools-mcp is an MCP server for Next.js development that acts as a thin connector, linking coding agents such as Claude and Cursor to a running Next.js 16+ dev server. It proxies the dev server's built-in MCP endpoint so agents can read live runtime errors, routes and logs.

Key features

01Automatic discovery of running Next.js dev servers
02Proxying of runtime tools from the /_next/mcp endpoint
03Access to runtime errors, routes and dev logs
04nextjs_docs gateway to version-matched bundled docs
05browser_eval gateway to the agent-browser CLI

Use cases

01Letting a coding agent inspect current runtime errors in a Next.js app
02Giving an agent visibility into project routes and dev server logs
03Pointing an agent to Next.js docs matching the installed version

MCP support

This is an MCP server that exposes nextjs_index, nextjs_call, nextjs_docs and browser_eval tools to MCP clients such as Claude and Cursor. nextjs_call forwards requests to runtime tools on the dev server.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

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

Run commandnpx -y next-devtools-mcp

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

npmnext-devtools-mcp0.3.6stdio

Tools

Saved tool list · updated 2w ago

Parameter	Type	Required	Description
ref	string	No
url	string	No
text	string	No
files	array	No
action	enum	No	The action to perform using browser automationstart \| navigate \| click \| type \| fill_form \| evaluate \| screenshot \| console_messages \| close \| drag \| upload_file \| list_tools
button	enum	No	left \| right \| middle
endRef	string	No
fields	array	No
script	string	No
browser	enum	No	chrome \| firefox \| webkit \| msedge
element	string	No
fullPage	boolean	No
headless	boolean	No
startRef	string	No
modifiers	array	No
endElement	string	No
errorsOnly	boolean	No
doubleClick	boolean	No
startElement	string	No

Details

From the project README

Next.js DevTools MCP

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

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

Or follow Amp's MCP docs with the config above.

Claude Code

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

Or edit your MCP settings file with the config above.

Codex

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

Windows 11: add environment variables and a longer startup timeout to .codex/config.toml:

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

Cursor

Install in Cursor

Or go to Cursor Settings → MCP → New MCP Server and use the config above.

Gemini

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

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

Google Antigravity

Add to .gemini/antigravity/mcp_config.json:

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

See the Antigravity MCP docs.

VS Code / Copilot

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

Or follow the official VS Code MCP setup guide.

Warp

Settings | AI | Manage MCP Servers → + Add:

Name: next-devtools
Command: npx
Arguments: -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

Tool	What it does
`nextjs_index`	Discover running Next.js dev servers and list each one's runtime MCP tools.
`nextjs_call`	Call a runtime tool on a discovered server (errors, routes, logs, Server Actions).
`nextjs_docs`	Gateway. Point the agent at version-accurate docs in `node_modules/next/dist/docs/`.
`browser_eval`	Gateway. Point the agent at the `agent-browser` CLI for browser automation.

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).

nextjs_index — discover servers

Scans common ports for running Next.js 16+ dev servers and lists each server's built-in runtime tools at /_next/mcp. No parameters.

Runtime tools exposed by Next.js (varies by version):

get_errors — current build, runtime, and type errors
get_logs — path to the dev log file (browser console + server output)
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

Output: JSON listing discovered servers (port, PID, URL) and their tools.

nextjs_call — run a runtime tool

Calls one runtime tool on a discovered server. Run nextjs_index first to find the port and tool name.

Input:

port (required) — dev server port
toolName (required) — runtime tool to invoke
args (optional) — arguments object, only if the tool requires them

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

Output: JSON with the tool's result. Upstream requests, including response-body reads, have a 60-second deadline. Cancelling an MCP request aborts its upstream network work; discovery also releases response bodies used only to detect the protocol.

nextjs_docs — find version-accurate docs

Does not fetch docs. Recent Next.js releases bundle their docs (markdown, matching your installed version) at node_modules/next/dist/docs/. This tool checks for those files before returning reading instructions. If an installed release has no bundled docs (including early 16.x releases), it offers https://nextjs.org/docs as a fallback and asks the agent to verify APIs against the installed version. Missing dependencies receive installation guidance instead. On Next.js below 16, it recommends npx @next/codemod@latest upgrade latest.

Input: topic (optional), project_path (optional, defaults to cwd). The tool resolves next/package.json from that project, including hoisted workspace dependencies, and returns an absolute docsPath for the installed package.

browser_eval — set up browser automation

Does not drive the browser. It detects whether agent-browser is installed and returns either the entry point (agent-browser skills get core --full) or the install steps (npm install -g agent-browser, then agent-browser install), so the agent runs the CLI directly.

Input: task (optional) — used only to tailor the guidance.

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:

Start it: npm run dev
Confirm Next.js 16+ (the /_next/mcp endpoint only exists there)
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

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.

next-devtools-mcp

About next-devtools-mcp

Key features

Use cases

MCP support

Configuration

Tools

Details

Next.js DevTools MCP

Requirements

Install

Client-specific setup

Quick Start

Tools

Migrating from 0.3.x

Privacy & Telemetry

Troubleshooting

Local Development

License

Comments

New to MCP?

What is MCP (Model Context Protocol)?

How do MCP servers differ from clients?

Should I use a local or a remote server?

How do I install a server in Claude, Cursor and others?

Are listed projects reviewed? What does “Verified” mean?

My project is listed. How do I claim it?