{
  "markdown": "# Next.js DevTools MCP\n\n[![npm next-devtools-mcp package](https://img.shields.io/npm/v/next-devtools-mcp.svg)](https://npmjs.org/package/next-devtools-mcp)\n\n`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.\n\nIt 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`](https://github.com/vercel-labs/agent-browser) CLI.\n\n> [!NOTE]\n> 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](#migrating-from-03x).\n\n## Requirements\n\n- [Node.js](https://nodejs.org/) v20.19 or a newer [LTS](https://github.com/nodejs/Release#release-schedule) version\n- [npm](https://www.npmjs.com/) or [pnpm](https://pnpm.io/)\n- Next.js 16+ with a running dev server (for `nextjs_index` / `nextjs_call`)\n\n## Install\n\nInstall for all your coding agents with [`add-mcp`](https://www.npmjs.com/package/add-mcp):\n\n```bash\nnpx add-mcp next-devtools-mcp@latest\n```\n\nAdd `-y` to skip the prompt and install to all detected agents. Add `-g` to install globally across all projects.\n\nOr add the config to your MCP client manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"next-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"next-devtools-mcp@latest\"]\n    }\n  }\n}\n```\n\n> [!NOTE]\n> `next-devtools-mcp@latest` keeps your client on the latest version.\n\n### Client-specific setup\n\n<details>\n<summary>Amp</summary>\n\n```bash\namp mcp add next-devtools -- npx next-devtools-mcp@latest\n```\n\nOr follow [Amp's MCP docs](https://ampcode.com/manual#mcp) with the config above.\n\n</details>\n\n<details>\n<summary>Claude Code</summary>\n\n```bash\nclaude mcp add next-devtools npx next-devtools-mcp@latest\n```\n\nOr edit your MCP settings file with the config above.\n\n</details>\n\n<details>\n<summary>Codex</summary>\n\n```bash\ncodex mcp add next-devtools -- npx next-devtools-mcp@latest\n```\n\n**Windows 11:** add environment variables and a longer startup timeout to `.codex/config.toml`:\n\n```toml\nenv = { SystemRoot=\"C:\\\\Windows\", PROGRAMFILES=\"C:\\\\Program Files\" }\nstartup_timeout_ms = 20_000\n```\n\n</details>\n\n<details>\n<summary>Cursor</summary>\n\n[Install in Cursor](https://cursor.com/en/install-mcp?name=next-devtools&config=eyJjb21tYW5kIjoibnB4IC15IG5leHQtZGV2dG9vbHMtbWNwQGxhdGVzdCJ9)\n\nOr go to `Cursor Settings` → `MCP` → `New MCP Server` and use the config above.\n\n</details>\n\n<details>\n<summary>Gemini</summary>\n\n```bash\n# Project\ngemini mcp add next-devtools npx next-devtools-mcp@latest\n\n# Global\ngemini mcp add -s user next-devtools npx next-devtools-mcp@latest\n```\n\n</details>\n\n<details>\n<summary>Google Antigravity</summary>\n\nAdd to `.gemini/antigravity/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"next-devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"next-devtools-mcp@latest\"]\n    }\n  }\n}\n```\n\nSee the [Antigravity MCP docs](https://antigravity.google/docs/mcp).\n\n</details>\n\n<details>\n<summary>VS Code / Copilot</summary>\n\n```bash\ncode --add-mcp '{\"name\":\"next-devtools\",\"command\":\"npx\",\"args\":[\"-y\",\"next-devtools-mcp@latest\"]}'\n```\n\nOr follow the official VS Code MCP setup guide.\n\n</details>\n\n<details>\n<summary>Warp</summary>\n\n`Settings | AI | Manage MCP Servers` → `+ Add`:\n- Name: `next-devtools`\n- Command: `npx`\n- Arguments: `-y, next-devtools-mcp@latest`\n\n</details>\n\n## Quick Start\n\nStart your Next.js dev server:\n\n```bash\nnpm run dev\n```\n\nNext.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.\n\nThen ask your agent about the running app:\n\n```\nNext Devtools, what errors are in my Next.js application?\nNext Devtools, show me the structure of my routes\nNext Devtools, what's in the development server logs?\n```\n\nThe agent calls `nextjs_index` to discover servers, then `nextjs_call` to query their real state.\n\n## Tools\n\n| Tool           | What it does                                                                              |\n| -------------- | ----------------------------------------------------------------------------------------- |\n| `nextjs_index` | Discover running Next.js dev servers and list each one's runtime MCP tools.                |\n| `nextjs_call`  | Call a runtime tool on a discovered server (errors, routes, logs, Server Actions).        |\n| `nextjs_docs`  | **Gateway.** Point the agent at version-accurate docs in `node_modules/next/dist/docs/`.  |\n| `browser_eval` | **Gateway.** Point the agent at the [`agent-browser`](https://github.com/vercel-labs/agent-browser) CLI for browser automation. |\n\nThe 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).\n\n<details>\n<summary><code>nextjs_index</code> — discover servers</summary>\n\nScans common ports for running Next.js 16+ dev servers and lists each server's built-in runtime tools at `/_next/mcp`. No parameters.\n\nRuntime tools exposed by Next.js (varies by version):\n- `get_errors` — current build, runtime, and type errors\n- `get_logs` — path to the dev log file (browser console + server output)\n- `get_page_metadata` — routes, pages, component metadata\n- `get_project_metadata` — project structure, config, dev server URL\n- `get_server_action_by_id` — resolve a Server Action ID to its source file\n\nOutput: JSON listing discovered servers (port, PID, URL) and their tools.\n\n</details>\n\n<details>\n<summary><code>nextjs_call</code> — run a runtime tool</summary>\n\nCalls one runtime tool on a discovered server. Run `nextjs_index` first to find the port and tool name.\n\nInput:\n- `port` (required) — dev server port\n- `toolName` (required) — runtime tool to invoke\n- `args` (optional) — arguments object, only if the tool requires them\n\n```jsonc\n{ \"port\": 3000, \"toolName\": \"get_errors\" }\n```\n\nOutput: JSON with the tool's result.\n\n</details>\n\n<details>\n<summary><code>nextjs_docs</code> — find version-accurate docs</summary>\n\nDoes **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`.\n\nInput: `topic` (optional), `project_path` (optional, defaults to cwd).\n\n</details>\n\n<details>\n<summary><code>browser_eval</code> — set up browser automation</summary>\n\nDoes **not** drive the browser. It detects whether [`agent-browser`](https://github.com/vercel-labs/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.\n\nInput: `task` (optional) — used only to tailor the guidance.\n\n</details>\n\n## Migrating from 0.3.x\n\nStarting in 0.4.0, `next-devtools-mcp` is a thin connector.\n\n**Changed:**\n- `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.\n\n**Removed:**\n- `init` tool — it only enforced the old docs-fetch workflow.\n- `upgrade_nextjs_16` and `enable_cache_components` tools and their prompts — now distributed as agent skills.\n- All `cache-components://`, `nextjs16://`, and `nextjs-fundamentals://` resources — superseded by the bundled docs.\n\nWhat remains: `nextjs_index`, `nextjs_call`, `nextjs_docs`, and `browser_eval`.\n\n## Privacy & Telemetry\n\n`next-devtools-mcp` collects anonymous usage telemetry to improve the tool:\n\n- **Tool usage** — which MCP tools are invoked (e.g. `nextjs_index`, `nextjs_call`)\n- **Error events** — anonymous error messages when tools fail\n- **Session metadata** — session ID, timestamps, basic environment (OS, Node.js version)\n\n**Not collected:** your code, file contents or paths, personal data, credentials, or tool arguments (only tool names).\n\nLocal files live under `~/.next-devtools-mcp/` (anonymous `telemetry-id`, `telemetry-salt`, and a debug log `mcp.log`).\n\n**Opt out** by setting the environment variable (add it to `~/.zshrc` / `~/.bashrc` to persist):\n\n```bash\nexport NEXT_TELEMETRY_DISABLED=1\n```\n\nDelete local telemetry data anytime:\n\n```bash\nrm -rf ~/.next-devtools-mcp\n```\n\n## Troubleshooting\n\n**`ERR_MODULE_NOT_FOUND` referencing `next-devtools-mcp/dist`** — clear your npx cache and restart your MCP client. The server reinstalls fresh.\n\n**`[error] No server info found`** — `nextjs_index` / `nextjs_call` need a running Next.js 16+ dev server:\n1. Start it: `npm run dev`\n2. Confirm Next.js 16+ (the `/_next/mcp` endpoint only exists there)\n3. Verify it started without errors\n\n`browser_eval` and `nextjs_docs` work without a dev server.\n\n## Local Development\n\n```bash\ngit clone https://github.com/vercel/next-devtools-mcp.git\ncd next-devtools-mcp\npnpm install\npnpm build\n```\n\nPoint your MCP client at the local build:\n\n```json\n{\n  \"mcpServers\": {\n    \"next-devtools\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/next-devtools-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\nOr with Codex:\n\n```bash\ncodex mcp add next-devtools-local -- node dist/index.js\n```\n\nSee the [Next.js MCP documentation](https://nextjs.org/docs/app/guides/mcp) for how MCP works with Next.js and coding agents.\n\n## License\n\nMIT\n",
  "bytes": 9794,
  "sha": "2ebea1bae2d9dae21a20ebda82b8cbf524eb8e15f4e16140dff8ef7f6dbc71c2",
  "repo_slug": "vercel/next-devtools-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vercel_next_devtools_mcp_c7f06925/readme"
}