为编码代理启用 Next.js MCP Server

Model Context Protocol (MCP) 是一个开放标准，允许 AI 代理和编码助手通过标准化接口与你的应用程序进行交互。

Next.js 提供了两个 MCP server，我们建议同时使用两者以获得最佳的代理体验：

1. Next.js MCP Server（内置）

适用于 Next.js 16 及以上版本

Next.js MCP server 暴露你的应用程序内部，允许代理：

访问实时应用程序状态和运行时信息
查询页面元数据、路由和渲染详情
检索构建错误、运行时错误和开发日志
检查 Server Actions 和组件层次结构

此 server 在你的 Next.js 开发服务器中运行，并提供对应用程序内部状态的直接访问。

2. Next DevTools MCP（外部包）

next-devtools-mcp 是一个独立的包，提供高级开发工具和指导：

Next.js 知识库：查询全面的 Next.js 文档和最佳实践
迁移和升级工具：使用 codemods 自动升级到 Next.js 16 的辅助工具
Cache Components 指南：Cache Components 的设置和配置协助
浏览器测试：Playwright MCP 集成，用于在浏览器中验证页面

此外，next-devtools-mcp 可以自动发现并直接与运行中的 Next.js 开发服务器通信，以访问其 MCP 工具（get_errors、get_logs、get_page_metadata 等）。

这两个 MCP server 共同为代理提供了底层应用程序内部信息和高级开发指导。

开始使用

内置的 Next.js MCP server 在 Next.js 16 或以上版本的开发环境中默认启用。

配置 Next DevTools MCP

要使用 Next DevTools MCP，请将 next-devtools-mcp 添加到项目根目录的 .mcp.json 文件中

.mcp.json

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

有关更多开发工具功能和配置选项，请查看 next-devtools-mcp 仓库。

与代理一起使用

兼容 MCP 的编码代理可以自动发现并连接到你的 Next.js 开发服务器。这为代理提供了关于你项目的丰富上下文。

代理辅助开发的好处

代理可以：

提供上下文感知的建议：根据你现有的结构推荐添加新功能的正确位置
查询实时应用程序状态：在开发过程中检查当前配置、路由和中间件
理解你的 app router 页面布局：准确知道页面中渲染了哪个页面和布局
提供准确的实现：生成遵循你项目模式和约定的代码

开发工作流

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

Terminal

npm run dev

将你的编码代理连接到运行中的 Next.js 实例
在浏览器中打开你的应用程序以查看页面。
向你的代理查询见解和诊断（参见下面的示例）

可用的 Next.js MCP 工具

实验性的 Next.js MCP server 提供以下工具：

get_errors：从你的开发服务器检索当前的构建错误、运行时错误和类型错误
get_logs：访问开发服务器日志和控制台输出
get_page_metadata：获取特定页面的元数据，包括路由、组件和渲染信息
get_project_metadata：检索项目结构、配置和整体元数据
get_server_action_by_id：通过 ID 查找 Server Actions 以进行调试和检查

示例

错误检测和诊断

代理可以查询你运行中的 Next.js 应用程序以获取实时错误信息：

User: "What errors are currently in my application?"

代理操作：

调用 Next.js MCP server 提供的 get_errors 工具
从开发服务器检索当前的构建错误、运行时错误和类型错误
分析错误并提供可操作的修复方案

代理响应（点击展开）

> fix errors on the page
 
⏺ I'll help you fix the errors on the page. Let me first check what errors exist by looking at the
  current state of the project.
 
⏺ next-devtools - nextjs_runtime (MCP)(action: "discover_servers")
⏺ next-devtools - nextjs_runtime (MCP)(action: "call_tool", toolName: "get_errors")
 
⏺ I found a hydration error on the /about page. The error shows that the server is rendering
  "server" but the client is rendering "client", causing a mismatch. Let me create a todo list and fix
   this issue.
 
⏺ Perfect! Now let me check for errors on the page.           01:14 PM  claude-sonnet-4-5-20250929
 
⏺ next-devtools - nextjs_runtime (MCP)(action: "call_tool", toolName: "get_errors")
  ⎿ {
      "success": true,
      "port": 3000,
      "toolName": "get_errors",
      "result": {
        "content": [
          {
            "type": "text",
            "text": "# Found errors in 1 browser session(s)\n\n## Session: /about\n\n**1 error(s)
     found**\n\n### Runtime Errors\n\n#### Error 1 (Type: recoverable)\n\n**Error**: Hydration failed

这展示了同时启用两个 MCP server 的强大之处：Next.js MCP server 直接从你的应用程序提供实时诊断，而 next-devtools-mcp 可以提供最佳实践和迁移路径的指导。

升级和最佳实践

你还可以寻求 Next.js 概念和迁移方面的帮助：

User: "Help me upgrade my Next.js app to version 16"

代理将使用 next-devtools-mcp 分析你的当前版本，通过 codemods 引导你完成自动迁移，并为处理破坏性更改（如异步 Request API、动态路由段和 route handler 返回类型）提供分步说明。

你还可以询问概念性问题：

User: "When should I use 'use client' in App Router?"

代理将通过 next-devtools-mcp 查询 Next.js 知识库，并提供基于文档的解释以及来自你代码库的示例。

故障排除

MCP server 未连接

确保你使用的是 Next.js v16 或以上版本
启动你的开发服务器：npm run dev
重启你的开发服务器
检查你的 MCP 客户端是否配置了正确的路径
将 MCP server 添加到你的代理设置中