Next.js DevTools MCP
OfficialIt is an MCP server that connects coding agents to a running Next.js 16+ dev server (and provides docs/browser-automation gateways).
Discover running Next.js dev servers – scans for dev servers and lists their built-in MCP tools (
nextjs_index).Query live app state – call runtime tools on a discovered server to get errors, logs, route/page metadata, project config, and Server Action details (
nextjs_call).Find version-accurate docs – locates the Next.js docs bundled with the installed package so the agent reads the correct version (
nextjs_docs).Set up browser automation – points the agent to the
agent-browserCLI for real browser tasks like clicking, typing, and screenshots (browser_eval).Work without a dev server – docs and browser automation tools function even when no Next.js server is running.
Provides a comprehensive suite of development tools for Next.js applications, enabling runtime diagnostics, route structure analysis, server log inspection, and direct access to official Next.js documentation and migration guides.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Next.js DevTools MCP initialize context and show me the current route structure"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Docs and migration workflows no longer live in this server. Next.js bundles its own docs atnode_modules/next/dist/docs/, and upgrade / Cache Components workflows are distributed as agent skills. See Migrating from 0.3.x.
Requirements
Next.js 16+ with a running dev server (for
nextjs_index/nextjs_call)
Related MCP server: MCP Multi-Context Hook Generator
Install
Install for all your coding agents with add-mcp:
npx add-mcp next-devtools-mcp@latestAdd -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"]
}
}
}next-devtools-mcp@latest keeps your client on the latest version.
Client-specific setup
amp mcp add next-devtools -- npx next-devtools-mcp@latestOr follow Amp's MCP docs with the config above.
claude mcp add next-devtools npx next-devtools-mcp@latestOr edit your MCP settings file with the config above.
codex mcp add next-devtools -- npx next-devtools-mcp@latestWindows 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_000Or go to Cursor Settings → MCP → New MCP Server and use the config above.
# Project
gemini mcp add next-devtools npx next-devtools-mcp@latest
# Global
gemini mcp add -s user next-devtools npx next-devtools-mcp@latestAdd to .gemini/antigravity/mcp_config.json:
{
"mcpServers": {
"next-devtools": {
"command": "npx",
"args": ["-y", "next-devtools-mcp@latest"]
}
}
}See the Antigravity MCP docs.
code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'Or follow the official VS Code MCP setup guide.
Settings | AI | Manage MCP Servers → + Add:
Name:
next-devtoolsCommand:
npxArguments:
-y, next-devtools-mcp@latest
Quick Start
Start your Next.js dev server:
npm run devNext.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 |
| Discover running Next.js dev servers and list each one's runtime MCP tools. |
| Call a runtime tool on a discovered server (errors, routes, logs, Server Actions). |
| Gateway. Point the agent at version-accurate docs in |
| Gateway. Point the agent at the |
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).
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 errorsget_logs— path to the dev log file (browser console + server output)get_page_metadata— routes, pages, component metadataget_project_metadata— project structure, config, dev server URLget_server_action_by_id— resolve a Server Action ID to its source file
Output: JSON listing discovered servers (port, PID, URL) and their tools.
Calls one runtime tool on a discovered server. Run nextjs_index first to find the port and tool name.
Input:
port(required) — dev server porttoolName(required) — runtime tool to invokeargs(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.
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.
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_docsno longer fetches docs over the network. It points the agent at the docs Next.js bundles atnode_modules/next/dist/docs/(or recommends upgrading). Thenextjs-docs://llms-indexresource is removed.
Removed:
inittool — it only enforced the old docs-fetch workflow.upgrade_nextjs_16andenable_cache_componentstools and their prompts — now distributed as agent skills.All
cache-components://,nextjs16://, andnextjs-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=1Delete local telemetry data anytime:
rm -rf ~/.next-devtools-mcpTroubleshooting
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 devConfirm Next.js 16+ (the
/_next/mcpendpoint 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 buildPoint 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.jsSee the Next.js MCP documentation for how MCP works with Next.js and coding agents.
License
MIT
Available Tools
4 toolsbrowser_evalB
Set up and use browser automation for this project via the agent-browser CLI.
This tool does NOT drive the browser itself. It points you at agent-browser — a fast, native browser-automation CLI built for agents (https://github.com/vercel-labs/agent-browser) — and tells you how to install it (if needed) and where to start. You then run its commands directly (you have shell access), which is faster and more capable than proxying automation through MCP.
Call this when you need to open pages, click, type, screenshot, or capture console errors in a real browser.
Inputs: task.
nextjs_callA
Call a specific MCP tool on a running Next.js development server.
REQUIREMENTS:
Port number of the target Next.js dev server
Tool name to execute
Optional arguments object (if the tool requires parameters)
Use 'nextjs_index' first to discover available servers, tools, and their input schemas. If 'nextjs_index' auto-discovery fails, ask the user for the port and call 'nextjs_index' again with the 'port' parameter.
IMPORTANT: When calling tools:
The 'args' parameter MUST be an object (e.g., {key: "value"}), NOT a string
If a tool doesn't require arguments, OMIT the 'args' parameter entirely - do NOT pass {} or "{}"
Check the tool's inputSchema from 'nextjs_index' to see what arguments are required
Common Next.js MCP tools include:
Error diagnostics (get compilation/runtime errors)
Route information (list all routes)
Build status (check compilation state)
Cache management (clear caches)
And more (varies by Next.js version)
Example usage:
Call 'nextjs_index' to see servers and tools
Call 'nextjs_call' with port=3000, toolName="get_errors" to get errors from server on port 3000
Inputs: args, port, toolName.
nextjs_docsA
Find the version-accurate Next.js documentation for THIS project.
This tool does NOT fetch documentation. Next.js 16+ ships its full docs inside the installed package at node_modules/next/dist/docs/ (markdown), kept in sync with the exact version you have installed. This tool tells you where those docs are and how to read them — so you read the docs that match this project, not a generic or outdated copy.
Call this before answering Next.js questions or writing Next.js code. Then read the relevant guide from the path it returns. If the project is on an older Next.js, it will tell you how to upgrade.
Inputs: topic, project_path.
nextjs_indexA
Discover all running Next.js development servers and list their available MCP tools.
WHEN TO USE THIS TOOL - Use proactively in these scenarios:
Before implementing ANY changes to the app: When asked to add, modify, or fix anything in the application:
"Add a loading state" → Check current component structure and routes first
"Fix the navigation" → Inspect existing routes and components
"Update the API endpoint" → Query current routes and data flows
"Add error handling" → Check runtime errors and component hierarchy
"Refactor the auth logic" → Inspect current auth implementation and routes
"Optimize performance" → Check runtime diagnostics and component tree Use this to understand where changes should be made and what currently exists.
For diagnostic and investigation questions:
"What's happening?" / "What's going on?" / "Why isn't this working?"
"Check the errors" / "See what's wrong"
"What routes are available?" / "Show me the routes"
"Clear the cache" / "Reset everything"
Questions about build status, compilation errors, or runtime diagnostics
For agentic codebase search: Use this as FIRST CHOICE for searching the currently running app. If not found, fallback to static codebase search tools.
KEY PRINCIPLE: If the request involves the running Next.js application (whether to investigate OR modify it), query the runtime FIRST to understand current state before proceeding.
REQUIREMENTS:
Next.js 16 or later (MCP support was added in v16)
If you're on Next.js 15 or earlier, upgrade first by running 'npx @next/codemod@latest upgrade latest'
Next.js 16+ exposes an MCP (Model Context Protocol) endpoint at /_next/mcp automatically when the dev server starts. No configuration needed - MCP is enabled by default in Next.js 16 and later.
This tool discovers all running Next.js servers and returns:
Server port, PID, and URL
Complete list of available MCP tools for each server
Tool descriptions and input schemas
After calling this tool, use 'nextjs_call' to execute specific tools.
[IMPORTANT] If auto-discovery returns no servers:
Ask the user which port their Next.js dev server is running on
Call this tool again with the 'port' parameter set to the user-provided port
If the MCP endpoint is not available:
Ensure you're running Next.js 16 or later (upgrade with 'npx @next/codemod@latest upgrade latest')
Verify the dev server is running (npm run dev)
Check that the dev server started successfully without errors
Inputs: port.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: browser automation via CLI, executing MCP tools on the dev server, accessing local documentation, and discovering running servers and tools. There is no overlap or ambiguity.
Tools use a consistent snake_case convention. Three tools share the 'nextjs_' prefix, while 'browser_eval' deviates slightly but still follows the same pattern. The naming is predictable and readable.
With 4 tools, the set is well-scoped for a Next.js DevTools MCP server. Each tool covers a necessary aspect: discovery, execution, documentation access, and browser automation. No redundant or missing tools.
The tool surface covers the primary needs for interacting with a Next.js development environment: discovering server state, executing diagnostics, accessing version-accurate docs, and automating browser testing. There are no obvious gaps.
Maintenance
Related MCP Connectors
Git-backed platform for skills, tools, and context for AI agents
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Connect AI agents to ProductNow's context engine to search, create, review, and act.
Integrate Connext AI into agentic workflows, enabling Connext product-aware assistance.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides AI agents with access to a comprehensive database of 200+ Next.js documentation URLs for intelligent document selection and retrieval. Enables Claude and other AI assistants to analyze user queries and recommend the most relevant Next.js documentation pages.113MIT
- FlicenseNot gradedqualityDmaintenanceAutomatically generates typed React hooks for Next.js projects by crawling API routes, GraphQL queries, and components. Analyzes pages to suggest optimal render modes (SSR/CSR/ISR) and produces comprehensive documentation with AI-powered guidance.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to automate Next.js development including project scaffolding, React component generation, API route creation, and full-stack application workflows with TypeScript and Tailwind CSS support.MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible clients to inspect Next.js codebases, analyze App Router and Pages Router structure, discover API routes, and audit build performance through controlled tools.MIT