Next.js DevTools MCP

官方

next-devtools-mcp 是一个 MCP 服务器，为 Claude 和 Cursor 等 AI 编码助手提供 Next.js 开发工具和实用程序。

GitHub
821
试用此 MCP赞助

你可以用 Next Js DevTools MCP 做什么？

  • 发现开发服务器 — 让助手运行 nextjs_index 并列出正在运行的 Next.js 16+ 开发服务器及其运行时工具。
  • 查询实时应用状态 — 使用 nextjs_call 从特定开发服务器端口获取当前错误、路由、日志或 Server Actions。
  • 查找与版本匹配的文档 — 让 nextjs_docs 在 node_modules/next/dist/docs/ 中定位与已安装版本对应的捆绑 Next.js 文档。
  • 设置浏览器自动化 — 让 browser_eval 检测 agent-browser 并返回安装步骤或 CLI 入口点以供直接使用。

文档

Next.js DevTools MCP

npm next-devtools-mcp package

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/ 处捆绑了自己的文档，升级 / Cache Components 工作流以代理技能的形式分发。请参阅 从 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 
amp mcp add next-devtools -- npx next-devtools-mcp@latest

或按照 Amp 的 MCP 文档 使用上述配置。

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

或使用上述配置编辑您的 MCP 设置文件。

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

Windows 11： 向 .codex/config.toml 添加环境变量和更长的启动超时时间：

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

在 Cursor 中安装

或前往 Cursor Settings → MCP → New MCP Server 并使用上述配置。

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

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

添加到 .gemini/antigravity/mcp_config.json：

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

请参阅 Antigravity MCP 文档。

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

或遵循官方的 VS Code MCP 设置指南。

Warp

Settings | AI | Manage MCP Servers → + Add：

  • 名称：next-devtools
  • 命令：npx
  • 参数：-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 来查询它们的真实状态。

工具

工具功能
nextjs_index发现正在运行的 Next.js 开发服务器，并列出每个服务器的运行时 MCP 工具。
nextjs_call在已发现的服务器上调用运行时工具（错误、路由、日志、Server Actions）。
nextjs_docs网关。 将代理指向 node_modules/next/dist/docs/ 中与版本精确匹配的文档。
browser_eval网关。 将代理指向 agent-browser CLI 以进行浏览器自动化。

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

nextjs_index — 发现服务器

扫描常见端口以查找正在运行的 Next.js 16+ 开发服务器，并在 /_next/mcp 列出每个服务器的内置运行时工具。无参数。

Next.js 暴露的运行时工具（因版本而异）：

  • get_errors — 当前的构建、运行时和类型错误
  • get_logs — 开发日志文件的路径（浏览器控制台 + 服务器输出）
  • get_page_metadata — 路由、页面、组件元数据
  • get_project_metadata — 项目结构、配置、开发服务器 URL
  • get_server_action_by_id — 将 Server Action ID 解析为其源文件

输出：JSON，列出已发现的服务器（端口、PID、URL）及其工具。

nextjs_call — 运行运行时工具

在已发现的服务器上调用一个运行时工具。先运行 nextjs_index 以查找端口和工具名称。

输入：

  • port（必需）— 开发服务器端口
  • toolName（必需）— 要调用的运行时工具
  • args（可选）— 参数对象，仅当工具需要时
{ "port": 3000, "toolName": "get_errors" }

输出：包含工具结果的 JSON。上游请求（包括响应体读取）有 60 秒的截止时间。取消 MCP 请求会中止其上游网络工作；发现过程也会释放仅用于检测协议的响应体。

nextjs_docs — 查找与版本精确匹配的文档

不获取文档。最近的 Next.js 版本在 node_modules/next/dist/docs/ 捆绑了它们的文档（markdown，与您安装的版本匹配）。此工具在返回阅读说明之前检查这些文件。如果安装的版本没有捆绑文档（包括早期的 16.x 版本），它会提供 https://nextjs.org/docs 作为后备方案，并要求代理根据安装的版本验证 API。缺失的依赖项会收到安装指南。在低于 16 的 Next.js 上，它推荐 npx @next/codemod@latest upgrade latest。

输入：topic（可选），project_path（可选，默认为当前工作目录）。该工具从该项目解析 next/package.json，包括提升的工作区依赖项，并返回已安装包的绝对 docsPath。

browser_eval — 设置浏览器自动化

不驱动浏览器。它检测 agent-browser 是否已安装，并返回入口点（agent-browser skills get core --full）或安装步骤（npm install -g agent-browser，然后 agent-browser install），以便代理直接运行 CLI。

输入：task（可选）— 仅用于定制指南。

从 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