Next.js 开发工具 MCP

next-devtools-mcp 是一个模型上下文协议 (MCP) 服务器，为 Claude 和 Cursor 等编码助手提供 Next.js 开发工具和实用程序。

快速入门

要求

• Node.js v20.19 或更高版本的 最新维护版 LTS
• npm 或 pnpm

使用 add-mcp 安装

为所有编码助手安装 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 可确保您的 MCP 客户端始终使用最新版本的 Next.js 开发工具 MCP 服务器。

MCP 客户端配置

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

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

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 16+ 项目（推荐）

要充分发挥运行时诊断功能，请启动您的 Next.js 开发服务器：

npm run dev

Next.js 16+ 默认启用了 MCP，地址为 http://localhost:3000/_next/mcp（或您的开发服务器使用的其他端口）。next-devtools-mcp 服务器会自动发现并连接到它。

⚠️ 重要提示：每次启动 Next.js 会话时，请先调用 init 工具以设置正确的上下文：

使用 init 工具设置 Next.js 开发工具上下文

这将初始化 MCP 上下文，确保 AI 助手在所有查询中都使用官方 Next.js 文档。

初始化完成后，您可以尝试以下提示来探索运行时诊断功能：

Next Devtools，我的 Next.js 应用程序中有哪些错误？

Next Devtools，展示我的路由结构

Next Devtools，开发服务器日志中有什么内容？

您的编码助手将使用 nextjs_index 和 nextjs_call 工具查询您正在运行的应用程序的实际状态。

对于所有 Next.js 项目

无论 Next.js 版本如何，您都可以使用开发自动化和文档工具：

Next Devtools，帮我将我的 Next.js 应用升级到 16 版

Next Devtools，启用我 Next.js 应用中的缓存组件

Next Devtools，搜索 Next.js 文档中的 generateMetadata

💡 专业提示：在每个会话中自动初始化

为了让您的 AI 助手在每次 Next.js 会话开始时无需提示即可自动调用 init 工具，请将以下指令添加到您的代理配置文件中：

**在开始处理 Next.js 项目时，务必首先调用 next-devtools-mcp 中的 `init` 工具，以设置正确的上下文并确立文档优先的要求。此操作应自动执行，无需提示。**

在使用 Next.js 时，应在会话开始时始终调用 next-devtools-mcp 中的 init 工具，以建立适当的上下文和文档优先要求。

**Next.js 初始化**：当开始处理 Next.js 项目时，应首先自动调用 next-devtools-mcp 服务器中的 `init` 工具。这将建立正确的上下文，并确保所有 Next.js 相关查询都使用官方文档。

这样做有何意义：

• ✅ 确保在所有 Next.js 工作中保持一致的上下文
• ✅ 自动确立“文档优先”的要求
• ✅ 无需每次都手动调用 init
• ✅ 适用于您所有的 Next.js 项目

MCP 资源

知识库资源会自动提供给您的编程助手，并被划分为多个重点部分，以便高效管理上下文。当前资源 URI 如下：

这些资源由您的编程助手按需加载，提供有针对性的知识，而不会使上下文窗口过于拥挤。

MCP 提示语

预配置的提示语，用于帮助处理常见的 Next.js 开发任务：

MCP 工具

// 第一步：发现服务器和工具
// （先调用 nextjs_index）

// 第二步：调用特定工具
{
  "port": 3000,
  "toolName": "get_errors"
  // args 是可选的，只有当工具需要参数时才需要
}

Next Devtools，帮我在我 Next.js 16 应用中启用缓存组件

{
  "tool": "enable_cache_components",
  "args": {
    "project_path": "/path/to/project"
  }
}

隐私与遥测

收集的数据

next-devtools-mcp 会收集匿名使用遥测数据，以帮助改进该工具。收集以下数据：

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

不会收集的内容：

• 您的项目代码、文件内容或文件路径
• 个人信息或可识别数据
• API 密钥、凭据或其他敏感配置
• 传递给工具的参数（工具名称除外）

本地文件会写入 ~/.next-devtools-mcp/ 目录下（包含匿名的 telemetry-id、telemetry-salt 和调试日志 mcp.log）。事件会在后台发送到遥测端点，以帮助我们了解使用模式并提高可靠性。

选择退出

要完全禁用遥测，请设置环境变量：

export NEXT_TELEMETRY_DISABLED=1

将其添加到您的 shell 配置文件（如 ~/.bashrc、~/.zshrc）以使其永久生效。

您也可以随时删除本地遥测数据：

rm -rf ~/.next-devtools-mcp

故障排除

模块未找到错误

如果您遇到类似以下错误：

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '...\next-devtools-mcp\dist\resources\(cache-components)\...'

解决方案： 清除 npx 缓存并重启您的 MCP 客户端（Cursor、Claude Code 等）。服务器将被重新安装。

“未找到服务器信息”错误

如果您看到 [error] No server info found：

解决方案：

1. 确保您的 Next.js 开发服务器正在运行：npm run dev
2. 如果您使用的是 Next.js 15 或更早版本，请使用 upgrade_nextjs_16 工具升级到 Next.js 16+
3. 验证您的开发服务器是否成功启动且没有错误

注意： nextjs_index 和 nextjs_call 工具需要 Next.js 16+ 并且开发服务器正在运行。其他工具（nextjs_docs、browser_eval、upgrade_nextjs_16、enable_cache_components）无需运行服务器即可使用。

本地开发

要在本地运行 MCP 服务器进行开发：

1. 克隆仓库

2. 安装依赖项：

   pnpm install
   pnpm build
   

3. 配置您的 MCP 客户端以使用本地版本：

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

   注意：将 /absolute/path/to/next-devtools-mcp 替换为您克隆仓库的实际绝对路径。

   或者手动添加，例如使用 codex：

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

功能

该 MCP 服务器通过三种主要机制，为编码代理提供全面的 Next.js 开发能力：

1. 运行时诊断与实时状态访问（Next.js 16+）

直接连接到您正在运行的 Next.js 开发服务器内置的 MCP 端点，以查询：

• 实时构建和运行时错误
• 应用程序路由、页面和组件元数据
• 开发服务器日志和诊断信息
• Server Actions 和组件层级结构

2. 开发自动化

针对常见 Next.js 工作流的工具：

• 使用官方 codemod 自动完成 Next.js 16 升级
• 带有错误检测和自动修复功能的 Cache Components 迁移与设置
• 通过 Playwright 集成浏览器测试，实现视觉验证

3. 知识库与文档

• 精选的 Next.js 16 知识库（包含 12 个关于 Cache Components、异步 API 等主题的重点资源）
• 通过搜索 API 直接访问官方 Next.js 文档
• 预配置的提示，用于升级指导和 Cache Components 的启用

了解更多： 请参阅 Next.js MCP 文档，了解 MCP 服务器如何与 Next.js 及编码代理协同工作。

工作原理

本包提供一个 桥接 MCP 服务器，将您的编码代理与 Next.js 开发工具连接起来：

编码代理
      ↓
  next-devtools-mcp（本包）
      ↓
      ├─→ Next.js 开发服务器 MCP 端点（/_next/mcp）← 运行时诊断
      ├─→ Playwright MCP 服务器 ← 浏览器自动化
      └─→ 知识库与工具 ← 文档、升级、设置自动化

关键架构要点：

1. 适用于 Next.js 16+ 项目：该服务器会自动发现并连接到您正在运行的 Next.js 开发服务器在 http://localhost:PORT/_next/mcp 上的内置 MCP 端点。这使得编码代理可以直接访问运行时错误、路由、日志和应用状态。

2. 适用于所有 Next.js 项目：提供开发自动化工具（升级、Cache Components 设置）、文档访问以及独立于运行时连接的浏览器测试功能。

3. 简单的工作流程：调用 nextjs_index 查看所有服务器及可用工具，然后使用特定端口和所需工具名称调用 nextjs_call 来执行相应操作。

许可证

MIT 许可证

next-devtools-mcp 快速上手指南

next-devtools-mcp 是一个基于模型上下文协议（MCP）的服务器，专为 Claude、Cursor 等 AI 编程助手设计，提供 Next.js 开发工具、运行时诊断能力及官方文档检索功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: v20.19 或更新的 LTS 版本（推荐最新维护版）。
• 包管理器: npm 或 pnpm。
• AI 客户端: 已安装支持 MCP 协议的编程助手（如 Cursor, Claude Code, VS Code Copilot 等）。

安装步骤

您可以选择使用自动化工具一键安装，或手动配置。

方式一：使用 add-mcp 自动安装（推荐）

该命令会自动检测项目中使用的 AI 代理并进行配置：

npx add-mcp next-devtools-mcp@latest

• 添加 -y 参数可跳过确认提示。
• 添加 -g 参数可全局安装到所有项目。

方式二：手动配置

如果您需要手动编辑 MCP 配置文件，请添加以下配置项：

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

注意：使用 @latest 标签可确保始终运行最新版本。

主流客户端快速配置命令

• Cursor: 点击 Install in Cursor 按钮，或在设置中手动添加上述 JSON。
• Claude Code:

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

• VS Code / Copilot:

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

• Gemini CLI:

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

基本使用

1. 启动 Next.js 开发服务器

对于 Next.js 16+ 项目，MCP 功能默认开启。请先启动您的开发服务器：

npm run dev

服务器将在 http://localhost:3000/_next/mcp（或对应端口）暴露接口，next-devtools-mcp 会自动发现并连接。

2. 初始化上下文（关键步骤）

在开始任何 Next.js 相关任务前，必须先调用 init 工具以建立正确的上下文和文档规范。

在 AI 对话框中输入：

Use the init tool to set up Next.js DevTools context

此操作将：

• 初始化 MCP 上下文。
• 强制 AI 在回答 Next.js 问题时优先查阅官方文档。
• 展示可用工具列表。

3. 常用场景示例

初始化完成后，您可以尝试以下指令：

查看运行时状态（仅限 Next.js 16+）：

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?

通用开发与文档查询（所有版本）：

Next Devtools, help me upgrade my Next.js app to version 16

Next Devtools, enable Cache Components in my Next.js app

Next Devtools, search Next.js docs for generateMetadata

💡 进阶技巧：自动初始化

为了避免每次会话都手动调用 init，您可以在配置文件中添加指令，让 AI 自动执行。

• Cursor: 在项目根目录创建 .cursorrules 文件，写入：

  When working with Next.js, always call the init tool from next-devtools-mcp at the start of the session to establish proper context and documentation requirements.
  

• Claude Code: 在 ~/.claude/CLAUDE.md 或项目下的 .claude/CLAUDE.md 中添加：

  **When starting work on a Next.js project, ALWAYS call the `init` tool from next-devtools-mcp FIRST to set up proper context and establish documentation requirements. Do this automatically without being asked.**
  

配置后，AI 将在每次处理 Next.js 任务时自动完成初始化，确保上下文一致且准确。