跳到内容
应用路由指南Next.js MCP 服务器

为编码代理启用 Next.js MCP 服务器

模型上下文协议（MCP）是一个开放标准，允许AI代理和编码助手通过标准化接口与您的应用程序交互。

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

1. Next.js MCP 服务器（内置）

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

Next.js MCP 服务器暴露您的应用程序内部信息，允许代理

  • 访问实时应用程序状态和运行时信息
  • 查询页面元数据、路由和渲染细节
  • 检索构建错误、运行时错误和开发日志
  • 检查服务器操作和组件层次结构

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

2. Next DevTools MCP（外部包）

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

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

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

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

开始使用

内置的 Next.js MCP 服务器在 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 开发服务器。这为代理提供了关于项目的丰富上下文。

代理辅助开发的益处

代理可以

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

开发工作流程

  1. 启动您的 Next.js 开发服务器
终端
npm run dev

  1. 将您的编码代理连接到正在运行的 Next.js 实例

  2. 在浏览器中打开您的应用程序以查看页面。

  3. 向您的代理查询见解和诊断信息（参见下面的示例）

可用的 Next.js MCP 工具

实验性的 Next.js MCP 服务器提供以下工具

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

示例

错误检测和诊断

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

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

代理操作

  • 调用 Next.js MCP 服务器提供的 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 服务器的强大功能：Next.js MCP 服务器直接从您的应用程序提供实时诊断，而 next-devtools-mcp 可以提供有关最佳实践和迁移路径的指导。

升级和最佳实践

您还可以寻求 Next.js 概念和迁移的帮助

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

代理将使用 next-devtools-mcp 分析您当前的版本，通过使用 codemods 进行自动化迁移来指导您，并提供处理破坏性更改的分步说明，例如异步请求 API、动态路由段和路由处理程序返回类型。

您也可以提出概念性问题

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

代理将通过 next-devtools-mcp 查询 Next.js 知识库，并提供来自您代码库的文档支持的解释和示例。

故障排除

MCP 服务器未连接

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