next-devtools-mcp

Next.js DevTools MCP

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

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

说明

文档和迁移工作流不再由此服务提供。Next.js 会将自己的文档打包在 node_modules/next/dist/docs/ 中，升级和 Cache Components 工作流则以 Agent 技能的形式分发。请参阅从 0.3.x 迁移。

要求

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

安装

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

npx add-mcp next-devtools-mcp@latest

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

也可以手动将配置添加到 MCP 客户端：

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

说明

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 会自动发现并连接到该端点，无需配置。

然后向 Agent 询问正在运行的应用：

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?

Agent 会调用 nextjs_index 发现服务，然后调用 nextjs_call 查询服务的实际状态。

工具

网关本身不会执行操作，而是告知 Agent 文档的位置或 CLI 的安装和运行方式，由 Agent 直接执行（比通过 MCP 代理更快）。

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

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

变更内容：

• nextjs_docs 不再通过网络获取文档。它会引导 Agent 查阅 Next.js 打包在 node_modules/next/dist/docs/ 中的文档（或建议升级）。nextjs-docs://llms-index 资源已移除。

已移除：

• init 工具——它仅用于强制执行旧的文档获取工作流。
• upgrade_nextjs_16 和 enable_cache_components 工具及其提示词——现在以 Agent 技能的形式分发。
• 所有 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

故障排除

引用 next-devtools-mcp/dist 的 ERR_MODULE_NOT_FOUND——清除 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

有关 MCP 如何与 Next.js 和编码 Agent 配合使用，请参阅 Next.js MCP 文档。

许可证

MIT