Next.js MCP Server (Official)

什么是 Next.js MCP Server (Official)？

官方的 Next.js MCP 服务器是 Vercel 的 next-devtools-mcp，它把 Claude、Cursor 等编码智能体连接到你正在运行的 Next.js 开发服务器，让它们读取实时的错误、路由、日志和编译问题。

从 Next.js 16 开始，开发服务器本身就在 /_next/mcp 提供了内置的 MCP 端点。next-devtools-mcp 是一个轻量连接器：它发现你本机上正在运行的 Next.js 16+ 开发服务器，并把它们的端点代理给智能体。它还提供两个网关工具，分别把智能体引导到 node_modules/next/dist/docs/ 中与版本匹配的文档，以及 agent-browser CLI。项目位于 vercel/next-devtools-mcp，采用 MIT 许可证，免费使用，无需 API key。

如何使用 Next.js MCP Server (Official)？

前置条件：

• Node.js v20.19 或更新的 LTS 版本
• npm 或 pnpm
• Next.js 16 或更高版本，并有正在运行的开发服务器（nextjs_index 和 nextjs_call 需要）

最快的安装方式会为本机检测到的所有编码智能体完成配置：

npx add-mcp next-devtools-mcp@latest

加上 -y 可跳过确认，加上 -g 可全局安装。也可以把它添加到项目根目录的 .mcp.json（或客户端的 MCP 配置）中：

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

然后用 npm run dev 启动应用。Next.js 16+ 默认在 http://localhost:3000/_next/mcp 启用该端点，next-devtools-mcp 会自动发现它，无需额外配置。请在浏览器中打开你正在开发的页面，因为 get_errors、get_page_metadata 等工具会读取活动的浏览器会话。

Claude Code

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

Cursor

使用 README 中的 “Install in Cursor” 链接，或者进入 Cursor Settings → MCP → New MCP Server，粘贴上面的配置。

VS Code

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

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。

README 还介绍了 Amp、Gemini CLI、Google Antigravity 和 Warp 的配置方法。

示例提示词：“Next Devtools, what errors are in my Next.js application?” 或 “Next Devtools, show me the structure of my routes.”

Next.js MCP Server (Official) 的主要功能

• 实时运行时上下文：智能体看到的是运行中应用的真实错误、路由和日志，而不是根据源码猜测。
• 自动发现：扫描常用端口，连接所有正在运行的 Next.js 16+ 开发服务器，也支持同时连接多个项目。
• 无需 next build 的编译检查：Turbopack 项目可以直接从开发服务器按路由返回编译问题。
• 与版本匹配的文档：nextjs_docs 把智能体引导到你所安装的 Next.js 版本自带的文档。
• 浏览器验证：browser_eval 告诉智能体如何安装和运行 agent-browser CLI。
• 官方且轻量：由 Vercel 维护；0.4.0 版本精简为四个工具。
• 隐私控制：匿名遥测可以通过 NEXT_TELEMETRY_DISABLED=1 关闭。

Next.js MCP Server (Official) 工具

服务器本身提供四个工具：

• nextjs_index 发现正在运行的开发服务器，并列出每个服务器暴露的运行时工具。
• nextjs_call 在已发现的服务器上调用一个运行时工具，参数为 port、toolName 和可选的 args。
• nextjs_docs 是网关工具，返回内置文档的路径（在 Next.js 16 以下版本会建议升级）。
• browser_eval 是网关工具，返回 agent-browser 的安装步骤；它本身并不驱动浏览器。

通过 nextjs_call，智能体可以访问 Next.js 在 /_next/mcp 提供的运行时工具（具体集合随版本变化）：get_errors、get_logs、get_page_metadata、get_project_metadata、get_routes 和 get_server_action_by_id，以及仅限 Turbopack 的 get_compilation_issues 和 compile_route，还有需要开启 experimental.requestInsights 的 get_request_insights。

Next.js MCP Server (Official) 的使用场景

• 修复运行时错误：“我的应用现在有哪些错误？” 智能体会调用 get_errors 并提出修复方案，例如针对 hydration 不匹配的问题。
• 熟悉陌生的代码库：“列出所有 App Router 和 Pages Router 的路由。”
• 检查改动能否编译：让智能体对 /blog/[slug] 运行 compile_route，而不是执行完整的 next build。
• 追踪 Server Action：用 get_server_action_by_id 把错误中的 action ID 定位回源文件。
• 用与已安装版本匹配的文档回答框架问题：“在 App Router 中什么时候应该使用 'use client'？”

Next.js MCP Server (Official) 与替代方案对比

• 内置的 /_next/mcp 端点是官方方案的核心。next-dev-loop 等智能体 skills 会直接调用它，因此无需 next-devtools-mcp 也能工作；而 MCP 包为智能体在不同项目和版本之间提供一套统一的工具。
• jazelly 的 Next.js MCP Server 是一个社区路由分析器。它扫描应用目录，从源码中提取 API 路由路径、HTTP 方法、参数和 schema，而不是从运行中的开发服务器获取。
• 如果需要更深入的浏览器调试，可以搭配 Chrome DevTools MCP Server 使用。

Next.js MCP Server (Official) 常见问题排查

• [error] No server info found：nextjs_index 和 nextjs_call 需要一个正在运行的 Next.js 16+ 开发服务器。用 npm run dev 启动，确认版本为 16 或更高，并检查启动过程没有报错。nextjs_docs 和 browser_eval 不需要开发服务器。
• 智能体无法连接：确认 next.config 中没有把 experimental.mcpServer 设为 false，重启开发服务器，并确认客户端已加载 MCP 配置。
• 出现引用 next-devtools-mcp/dist 的 ERR_MODULE_NOT_FOUND：清理 npx 缓存并重启 MCP 客户端。
• 旧工具不见了：init、upgrade_nextjs_16 和 enable_cache_components 已在 0.4.0 中移除；升级和 Cache Components 工作流现在以智能体 skills 的形式提供。