Skip to content
Back to search

next-devtools-mcp

Next.js Development for Coding Agent

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vercel--next-devtools-mcp/badge.svg)](/listings/vercel--next-devtools-mcp)

HTML

<a href="/listings/vercel--next-devtools-mcp"><img src="/api/listings/vercel--next-devtools-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install for all your coding agents with [`add-mcp`](https://www.npmjs.com/package/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

<details> <summary>Amp</summary>

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

Or follow [Amp's MCP docs](https://ampcode.com/manual#mcp) with the config above.

</details>

<details> <summary>Claude Code</summary>

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

Or edit your MCP settings file with the config above.

</details>

<details> <summary>Codex</summary>

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

</details>

<details> <summary>Cursor</summary>

[Install in Cursor](https://cursor.com/en/install-mcp?name=next-devtools&config=eyJjb21tYW5kIjoibnB4IC15IG5leHQtZGV2dG9vbHMtbWNwQGxhdGVzdCJ9)

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

</details>

<details> <summary>Gemini</summary>

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

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

</details>

<details> <summary>Google Antigravity</summary>

Add to `.gemini/antigravity/mcp_config.json`:

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

See the [Antigravity MCP docs](https://antigravity.google/docs/mcp).

</details>

<details> <summary>VS Code / Copilot</summary>

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

Or follow the official VS Code MCP setup guide.

</details>

<details> <summary>Warp</summary>

`Settings | AI | Manage MCP Servers` → `+ Add`: - Name: `next-devtools` - Command: `npx` - Arguments: `-y, next-devtools-mcp@latest`

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 311 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Next.js DevTools MCP
  2. [![npm next-devtools-mcp package](https://img.shields.io/npm/v/next-devtools-mcp.svg)](https://npmjs.org/package/next-devtools-mcp)
  3. `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.
  4. 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`](https://github.com/vercel-labs/agent-browser) CLI.
  5. > [!NOTE]
  6. > 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).
  7. ## Requirements
  8. - [Node.js](https://nodejs.org/) v20.19 or a newer [LTS](https://github.com/nodejs/Release#release-schedule) version
  9. - [npm](https://www.npmjs.com/) or [pnpm](https://pnpm.io/)
  10. - Next.js 16+ with a running dev server (for `nextjs_index` / `nextjs_call`)
  11. ## Install
  12. Install for all your coding agents with [`add-mcp`](https://www.npmjs.com/package/add-mcp):
  13. ```bash
  14. npx add-mcp next-devtools-mcp@latest
  15. ```
  16. Add `-y` to skip the prompt and install to all detected agents. Add `-g` to install globally across all projects.
  17. Or add the config to your MCP client manually:
  18. ```json
  19. {
  20. "mcpServers": {
  21. "next-devtools": {
  22. "command": "npx",
  23. "args": ["-y", "next-devtools-mcp@latest"]
  24. }
  25. }
  26. }
  27. ```
  28. > [!NOTE]
  29. > `next-devtools-mcp@latest` keeps your client on the latest version.
  30. ### Client-specific setup
  31. <details>
  32. <summary>Amp</summary>
  33. ```bash
  34. amp mcp add next-devtools -- npx next-devtools-mcp@latest
  35. ```
  36. Or follow [Amp's MCP docs](https://ampcode.com/manual#mcp) with the config above.
  37. </details>
  38. <details>
  39. <summary>Claude Code</summary>
  40. ```bash
  41. claude mcp add next-devtools npx next-devtools-mcp@latest
  42. ```
  43. Or edit your MCP settings file with the config above.
  44. </details>
  45. <details>
  46. <summary>Codex</summary>
  47. ```bash
  48. codex mcp add next-devtools -- npx next-devtools-mcp@latest
  49. ```
  50. **Windows 11:** add environment variables and a longer startup timeout to `.codex/config.toml`:
  51. ```toml
  52. env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
  53. startup_timeout_ms = 20_000
  54. ```
  55. </details>
  56. <details>
  57. <summary>Cursor</summary>
  58. [Install in Cursor](https://cursor.com/en/install-mcp?name=next-devtools&config=eyJjb21tYW5kIjoibnB4IC15IG5leHQtZGV2dG9vbHMtbWNwQGxhdGVzdCJ9)
  59. Or go to `Cursor Settings` → `MCP` → `New MCP Server` and use the config above.
  60. </details>
  61. <details>
  62. <summary>Gemini</summary>
  63. ```bash
  64. # Project
  65. gemini mcp add next-devtools npx next-devtools-mcp@latest
  66. # Global
  67. gemini mcp add -s user next-devtools npx next-devtools-mcp@latest
  68. ```
  69. </details>
  70. <details>
  71. <summary>Google Antigravity</summary>
  72. Add to `.gemini/antigravity/mcp_config.json`:
  73. ```json
  74. {
  75. "mcpServers": {
  76. "next-devtools": {
  77. "command": "npx",
  78. "args": ["-y", "next-devtools-mcp@latest"]
  79. }
  80. }
  81. }
  82. ```
  83. See the [Antigravity MCP docs](https://antigravity.google/docs/mcp).
  84. </details>
  85. <details>
  86. <summary>VS Code / Copilot</summary>
  87. ```bash
  88. code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'
  89. ```
  90. Or follow the official VS Code MCP setup guide.
  91. </details>
  92. <details>
  93. <summary>Warp</summary>
  94. `Settings | AI | Manage MCP Servers` → `+ Add`:
  95. - Name: `next-devtools`
  96. - Command: `npx`
  97. - Arguments: `-y, next-devtools-mcp@latest`
  98. </details>
  99. ## Quick Start
  100. Start your Next.js dev server:
  101. ```bash
  102. npm run dev
  103. ```
  104. 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.
  105. Then ask your agent about the running app:
  106. ```
  107. Next Devtools, what errors are in my Next.js application?
  108. Next Devtools, show me the structure of my routes
  109. Next Devtools, what's in the development server logs?
  110. ```
  111. The agent calls `nextjs_index` to discover servers, then `nextjs_call` to query their real state.
  112. ## Tools
  113. | Tool | What it does |
  114. | -------------- | ----------------------------------------------------------------------------------------- |
  115. | `nextjs_index` | Discover running Next.js dev servers and list each one's runtime MCP tools. |
  116. | `nextjs_call` | Call a runtime tool on a discovered server (errors, routes, logs, Server Actions). |
  117. | `nextjs_docs` | **Gateway.** Point the agent at version-accurate docs in `node_modules/next/dist/docs/`. |
  118. | `browser_eval` | **Gateway.** Point the agent at the [`agent-browser`](https://github.com/vercel-labs/agent-browser) CLI for browser automation. |
  119. 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).
  120. <details>
  121. <summary><code>nextjs_index</code> — discover servers</summary>
  122. Scans common ports for running Next.js 16+ dev servers and lists each server's built-in runtime tools at `/_next/mcp`. No parameters.
  123. Runtime tools exposed by Next.js (varies by version):
  124. - `get_errors` — current build, runtime, and type errors
  125. - `get_logs` — path to the dev log file (browser console + server output)
  126. - `get_page_metadata` — routes, pages, component metadata
  127. - `get_project_metadata` — project structure, config, dev server URL
  128. - `get_server_action_by_id` — resolve a Server Action ID to its source file
  129. Output: JSON listing discovered servers (port, PID, URL) and their tools.
  130. </details>
  131. <details>
  132. <summary><code>nextjs_call</code> — run a runtime tool</summary>
  133. Calls one runtime tool on a discovered server. Run `nextjs_index` first to find the port and tool name.
  134. Input:
  135. - `port` (required) — dev server port
  136. - `toolName` (required) — runtime tool to invoke
  137. - `args` (optional) — arguments object, only if the tool requires them
  138. ```jsonc
  139. { "port": 3000, "toolName": "get_errors" }
  140. ```
  141. 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.
  142. </details>
  143. <details>
  144. <summary><code>nextjs_docs</code> — find version-accurate docs</summary>
  145. 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`.
  146. 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.
  147. </details>
  148. <details>
  149. <summary><code>browser_eval</code> — set up browser automation</summary>
  150. Does **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.
  151. Input: `task` (optional) — used only to tailor the guidance.
  152. </details>
  153. ## Migrating from 0.3.x
  154. Starting in 0.4.0, `next-devtools-mcp` is a thin connector.
  155. **Changed:**
  156. - `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.
  157. **Removed:**
  158. - `init` tool — it only enforced the old docs-fetch workflow.
  159. - `upgrade_nextjs_16` and `enable_cache_components` tools and their prompts — now distributed as agent skills.
  160. - All `cache-components://`, `nextjs16://`, and `nextjs-fundamentals://` resources — superseded by the bundled docs.
  161. What remains: `nextjs_index`, `nextjs_call`, `nextjs_docs`, and `browser_eval`.
  162. ## Privacy & Telemetry
  163. `next-devtools-mcp` collects anonymous usage telemetry to improve the tool:
  164. - **Tool usage** — which MCP tools are invoked (e.g. `nextjs_index`, `nextjs_call`)
  165. - **Error events** — anonymous error messages when tools fail
  166. - **Session metadata** — session ID, timestamps, basic environment (OS, Node.js version)
  167. **Not collected:** your code, file contents or paths, personal data, credentials, or tool arguments (only tool names).
  168. Local files live under `~/.next-devtools-mcp/` (anonymous `telemetry-id`, `telemetry-salt`, and a debug log `mcp.log`).
  169. **Opt out** by setting the environment variable (add it to `~/.zshrc` / `~/.bashrc` to persist):
  170. ```bash
  171. export NEXT_TELEMETRY_DISABLED=1
  172. ```
  173. Delete local telemetry data anytime:
  174. ```bash
  175. rm -rf ~/.next-devtools-mcp
  176. ```
  177. ## Troubleshooting
  178. **`ERR_MODULE_NOT_FOUND` referencing `next-devtools-mcp/dist`** — clear your npx cache and restart your MCP client. The server reinstalls fresh.
  179. **`[error] No server info found`** — `nextjs_index` / `nextjs_call` need a running Next.js 16+ dev server:
  180. 1. Start it: `npm run dev`
  181. 2. Confirm Next.js 16+ (the `/_next/mcp` endpoint only exists there)
  182. 3. Verify it started without errors
  183. `browser_eval` and `nextjs_docs` work without a dev server.
  184. ## Local Development
  185. ```bash
  186. git clone https://github.com/vercel/next-devtools-mcp.git
  187. cd next-devtools-mcp
  188. pnpm install
  189. pnpm build
  190. ```
  191. Point your MCP client at the local build:
  192. ```json
  193. {
  194. "mcpServers": {
  195. "next-devtools": {
  196. "command": "node",
  197. "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"]
  198. }
  199. }
  200. }
  201. ```
  202. Or with Codex:
  203. ```bash
  204. codex mcp add next-devtools-local -- node dist/index.js
  205. ```
  206. See the [Next.js MCP documentation](https://nextjs.org/docs/app/guides/mcp) for how MCP works with Next.js and coding agents.
  207. ## License
  208. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.