vercel/next-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:
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:
> [!NOTE]
> next-devtools-mcp@latest keeps your client on the latest version.
Client-specific setup
Amp
Or follow Amp's MCP docs with the config above.
Claude Code
Or edit your MCP settings file with the config above.
Codex
**Windows 11:** add environment variables and a longer startup timeout to .codex/config.toml:
Cursor
Install in Cursor
Or go to Cursor Settings → MCP → New MCP Server and use the config above.
Gemini
Google Antigravity
Add to .gemini/antigravity/mcp_config.json:
See the Antigravity MCP docs.
VS Code / Copilot
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:
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:
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.