Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp 是一个模型上下文协议（MCP）服务器，可将 Claude 和 Cursor 等编码代理连接到正在运行的 Next.js 开发服务器。

它是一个轻量连接器。它能发现正在运行的 Next.js 16+ 开发服务器，并代理其内置的 MCP 端点（/_next/mcp），以便代理获取实时运行时错误、路由和日志。它还提供两个网关，引导代理使用可直接运行的工具：版本精确的文档和 agent-browser CLI。

[!NOTE] 文档和迁移工作流不再存在于本服务器中。Next.js 在 node_modules/next/dist/docs/ 处捆绑了自己的文档，升级/缓存组件工作流则作为代理技能分发。请参阅从 0.3.x 迁移。

环境要求

• Node.js v20.19 或更新的 LTS 版本
• npm 或 pnpm
• Next.js 16+ 且开发服务器正在运行（用于 nextjs_index / nextjs_call）

安装

使用 add-mcp 为所有编码代理安装：

npx add-mcp next-devtools-mcp@latest

添加 -y 可跳过提示并安装到所有检测到的代理。添加 -g 可在所有项目中全局安装。

或者手动将配置添加到你的 MCP 客户端：

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

[!NOTE] next-devtools-mcp@latest 可使你的客户端保持最新版本。

客户端特定设置

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

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

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

env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

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

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

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

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

快速开始

启动你的 Next.js 开发服务器：

npm run dev

Next.js 16+ 默认在 http://localhost:3000/_next/mcp 处启用其 MCP 端点。next-devtools-mcp 会自动发现并连接到它——无需配置。

然后向你的代理询问正在运行的应用程序：

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?

代理会调用 nextjs_index 来发现服务器，然后调用 nextjs_call 来查询它们的真实状态。

工具

网关本身不执行工作——它们告诉代理文档在哪里或如何安装/运行 CLI，然后代理直接运行它（比通过 MCP 代理更快）。

{ "port": 3000, "toolName": "get_errors" }

从 0.3.x 迁移

从 0.4.0 开始，next-devtools-mcp 是一个轻量连接器。

变更：

• nextjs_docs 不再通过网络获取文档。它引导代理使用 Next.js 在 node_modules/next/dist/docs/ 处捆绑的文档（或建议升级）。nextjs-docs://llms-index 资源已移除。

移除：

• init 工具 — 它仅强制执行旧的文档获取工作流。
• upgrade_nextjs_16 和 enable_cache_components 工具及其提示 — 现在作为代理技能分发。
• 所有 cache-components://、nextjs16:// 和 nextjs-fundamentals:// 资源 — 已被捆绑文档取代。

保留的内容：nextjs_index、nextjs_call、nextjs_docs 和 browser_eval。

隐私与遥测

next-devtools-mcp 收集匿名使用遥测数据以改进工具：

• 工具使用情况 — 调用了哪些 MCP 工具（例如 nextjs_index、nextjs_call）
• 错误事件 — 工具失败时的匿名错误消息
• 会话元数据 — 会话 ID、时间戳、基本环境（操作系统、Node.js 版本）

不收集： 你的代码、文件内容或路径、个人数据、凭据或工具参数（仅工具名称）。

本地文件位于 ~/.next-devtools-mcp/ 下（匿名 telemetry-id、telemetry-salt 和调试日志 mcp.log）。

退出 通过设置环境变量（将其添加到 ~/.zshrc / ~/.bashrc 以持久化）：

export NEXT_TELEMETRY_DISABLED=1

随时删除本地遥测数据：

rm -rf ~/.next-devtools-mcp

故障排除

ERR_MODULE_NOT_FOUND 引用 next-devtools-mcp/dist — 清除你的 npx 缓存并重启 MCP 客户端。服务器会全新安装。

[error] No server info found — nextjs_index / nextjs_call 需要正在运行的 Next.js 16+ 开发服务器：

1. 启动它：npm run dev
2. 确认 Next.js 16+（/_next/mcp 端点仅存在于该版本）
3. 验证它启动时没有错误

browser_eval 和 nextjs_docs 无需开发服务器即可工作。

本地开发

git clone https://github.com/vercel/next-devtools-mcp.git
cd next-devtools-mcp
pnpm install
pnpm build

将你的 MCP 客户端指向本地构建：

{
  "mcpServers": {
    "next-devtools": {
      "command": "node",
      "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"]
    }
  }
}

或使用 Codex：

codex mcp add next-devtools-local -- node dist/index.js

请参阅 Next.js MCP 文档，了解 MCP 如何与 Next.js 和编码代理协同工作。

许可证

MIT