A thin connector that bridges coding agents (like Claude and Cursor) to your running Next.js dev server, providing live runtime insights and development tooling.
Discover Running Next.js Dev Servers (nextjs_index): Automatically scan common ports to find all running Next.js 16+ dev servers and list their available MCP runtime tools (port, PID, URL, and tool schemas).
Query Live Runtime Data (nextjs_call): Call specific runtime tools on a discovered Next.js dev server, including:
get_errors — retrieve current build, runtime, and type errors
get_logs — access the dev log file (browser console + server output)
get_page_metadata — inspect routes, pages, and component metadata
get_project_metadata — view project structure, config, and dev server URL
get_server_action_by_id — resolve a Server Action ID to its source file
Find Version-Accurate Docs (nextjs_docs): Points agents at the exact Next.js documentation bundled with your installed version at node_modules/next/dist/docs/, ensuring docs match your project's version rather than outdated training data.
Set Up Browser Automation (browser_eval): Guides agents to install and use the agent-browser CLI for browser automation tasks (opening pages, clicking, typing, taking screenshots, capturing console errors) — without proxying through MCP for maximum speed.
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 "Install 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-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.
Next.js 16+ with a running dev server (for nextjs_index / nextjs_call)
Related MCP server: Next.js MCP Server
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.
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-devtools
Command: npx
Arguments: -y, next-devtools-mcp@latest
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.
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 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.
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.
Does not fetch docs. Next.js 16+ ships its full docs (markdown, matching your installed version) at node_modules/next/dist/docs/. This tool returns that path and how to read it, so the agent uses version-accurate docs instead of training-data guesses. On older Next.js, it recommends npx @next/codemod@latest upgrade latest.
Input: topic (optional), project_path (optional, defaults to cwd).
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.
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.
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-mcpERR_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.
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.
MIT
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.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool doesn't drive the browser but points to an external CLI. Lacks details on installation requirements, potential side effects, or system permissions needed, which is a gap for a setup tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences plus an additional paragraph. It is relatively concise but could be more structured (e.g., separate usage from behavior). No wasted words, but the middle sentence about what it doesn't do could be integrated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and usage context but omits parameter details and doesn't explain output or return values. For a simple tool with one optional param and no output schema, the missing parameter guidance is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional string parameter 'task' with 0% schema description coverage. The description does not explain what 'task' is, how to use it, or what values are expected, leaving the agent with no guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it sets up browser automation via agent-browser CLI. It distinguishes from sibling tools (nextjs_*) which are not browser-related. However, it includes a negative statement ('does NOT drive the browser itself') that adds clarity but also could be confusing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage condition: 'Call this when you need to open pages, click, type, screenshot, or capture console errors in a real browser.' It also notes that direct CLI usage is faster than MCP. No explicit when-not-to or alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | ||
| port | No | Port number of the Next.js dev server (required). | |
| toolName | No | Name of the Next.js MCP tool to call (required). Use 'nextjs_index' first to discover available tool names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. However, the description focuses on usage instructions (how to call) rather than behavioral traits like idempotency, side effects, or error handling. It does not reveal what happens when a tool fails or whether it is read-only. This leaves gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headers (REQUIREMENTS, IMPORTANT, Common tools, Example usage) and front-loads the core purpose. It is slightly verbose due to the list of common tools and repeated examples, but every sentence adds value. A minor trim could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no annotations, the description covers prerequisites (port, toolName, args), how to discover tools, and parameter formatting. It lacks details on output format or error responses, but for a tool that delegates to other tools, this is acceptable. Overall, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with the 'args' parameter lacking a description in schema. The description compensates by explaining that 'args' must be an object (not a string) and should be omitted if not needed. This adds significant meaning beyond the schema, though some parameter details (like type constraints for port) are already clear from schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb 'call' and resource 'MCP tool on a Next.js dev server'. It distinguishes from siblings like 'nextjs_index' by specifying that this tool executes a call rather than discovering tools. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: requires a port, tool name, and optional args; instructs to use 'nextjs_index' first for discovery. It includes important notes on args formatting and example usage. This fully informs the agent on correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | ||
| project_path | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It clearly states the tool does not fetch documentation but locates it, explains where docs are stored, and mentions upgrade guidance. This gives good transparency, though it could explicitly state it's read-only with no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence stating purpose, then clarifying behavior, then usage guidance. It is concise with no filler, though it could be slightly tightened without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose and usage but lacks details on output format (what exactly is returned, e.g., a path, a list) and error handling. Since no output schema exists, the description should provide more specifics on the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two undocumented parameters (topic, project_path), and schema description coverage is 0%. The description barely adds meaning: topic is implied by 'version-accurate documentation' and project_path by 'this project,' but no explicit format or constraints are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Find the version-accurate Next.js documentation for THIS project.' It distinguishes from sibling tools by specifying it deals with documentation, not execution or indexing, and explicitly says it does not fetch docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Call this before answering Next.js questions or writing Next.js code.' It also explains subsequent steps and upgrade handling. However, it does not explicitly exclude alternative tools or contrast with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| port | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description carries full burden. It discloses discovery behavior, requirements (Next.js 16+), fallback with port parameter, and what returns. Lacks specifics on error handling or latency but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headings, numbered lists, and bold for key points. Some slight redundancy, but each section earns its place. Content is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains return values (port, PID, URL, MCP tools list). Also covers prerequisites, fallback procedures, and next steps. Complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one optional parameter 'port' with no description. The description adds meaning by explaining its use as a fallback when auto-discovery fails, and instructs to ask user for port. Compensates for 0% schema coverage well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool discovers running Next.js servers and lists their MCP tools. It distinguishes from sibling nextjs_call by setting up a workflow for execution, and from nextjs_docs which is likely documentation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit scenarios for when to use: before implementing changes, for diagnostic questions, and as first choice for agentic codebase search. Includes fallback instructions and when to use nextjs_call, offering clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Git-backed platform for skills, tools, and context for AI agents
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Integrate Connext AI into agentic workflows, enabling Connext product-aware assistance.
The documentation, as a tool your agent can call: 950+ AI-dev guides. Search + fetch tools.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/vercel/next-devtools-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
