mcp/next-devtools-mcp

next-devtools-mcp：Next.js DevTools MCP服务器

镜像概述和主要用途

next-devtools-mcp 是一个Model Context Protocol (MCP)服务器，为AI编码助手提供Next.js开发工具和实用程序。它通过MCP协议集成各类开发工具，帮助开发者在Next.js项目中实现浏览器自动化测试、缓存组件配置、文档检索、运行时诊断及版本升级等开发任务。

MCP信息

镜像构建信息

可用工具（5个）

工具详情

工具：browser_eval

使用Playwright浏览器自动化来自动化和测试Web应用程序。该工具连接到playwright-mcp服务器，提供对所有Playwright功能的访问。

页面验证关键提示：

在Next.js项目中验证页面时（尤其是在升级或测试期间），必须使用浏览器自动化加载页面，而不是curl或简单的HTTP请求。原因如下：

• 浏览器自动化实际渲染页面并执行JavaScript（curl仅获取HTML）
• 检测运行时错误、hydration问题和客户端问题，这些是curl无法捕获的
• 验证完整的用户体验，而不仅仅是HTTP状态码
• 通过console_messages操作捕获浏览器控制台错误和警告

Next.js项目重要提示：

如果使用Next.js应用程序，优先使用'nextjs_runtime'工具，而非浏览器控制台日志转发。Next.js内置的MCP集成提供更优的错误报告、构建诊断和运行时信息，直接来自Next.js开发服务器。仅当nextjs_runtime工具不可用或特别需要测试客户端浏览器行为时，才将browser_eval的console_messages操作作为后备。

可用操作：

• start：启动浏览器自动化（需要时自动安装）。始终启用详细日志。
• navigate：导航到URL
• click：点击元素
• type：在元素中输入文本
• fill_form：一次性填写多个表单字段
• evaluate：在浏览器上下文中执行JavaScript
• screenshot：截取页面截图
• console_messages：获取浏览器控制台消息（对于Next.js，优先使用nextjs_runtime工具）
• close：关闭浏览器
• drag：执行拖放操作
• upload_file：上传文件
• list_tools：列出服务器提供的所有浏览器自动化工具

注意：playwright-mcp服务器在需要时会自动安装。

工具：enable_cache_components

完成Next.js 16的缓存组件设置。

该工具处理启用和验证缓存组件的所有步骤：

• 配置：更新Next.js 16的cacheComponents标志（16.0.0为实验性，更高版本为稳定版），移除不兼容标志
• 开发服务器：启动启用MCP的开发服务器（__NEXT_EXPERIMENTAL_MCP_SERVER=true）
• 错误检测：通过浏览器自动化加载所有路由，使用Next.js MCP收集错误
• 自动修复：添加Suspense边界、"use cache"指令、generateStaticParams、cacheLife配置文件、缓存标签
• 验证：确保所有路由零错误运行

核心功能：

• 一次性启动开发服务器（无需重启）
• 使用Next.js MCP工具自动检测错误
• 通过浏览器自动化进行基于浏览器的测试
• Fast Refresh即时应用修复
• 针对所有错误类型的全面修复策略
• 支持"use cache"、"use cache: private"、Suspense边界
• 通过cacheTag()和cacheLife()配置实现缓存失效

要求：

• Next.js 16.0.0+（仅支持稳定版或canary版 - 不支持beta版）
• 首选干净的工作目录
• 已安装浏览器自动化（需要时自动安装）

知识库涵盖：

• 缓存组件机制
• 错误模式和解决方案
• 缓存策略（静态vs动态）
• 高级模式（cacheLife、cacheTag、草稿模式）
• 构建行为和预取
• 来自125+示例的测试驱动模式

工具：nextjs_docs

搜索和检索Next.js官方文档。首先搜索MCP资源（Next.js 16知识库）获取最新信息，若未找到则回退到Next.js官方文档。提供对全面的Next.js指南、API参考和最佳实践的访问。

工具：nextjs_runtime

与运行中的Next.js开发服务器的MCP端点交互，查询运行时信息、诊断和内部信息。

使用场景 - 在以下情况主动使用：

1. 实施任何应用更改之前：当需要添加、修改或修复应用中的任何内容时：

   • "添加加载状态" → 首先检查当前组件结构和路由
   • "修复导航问题" → 检查现有路由和组件
   • "更新API端点" → 查询当前路由和数据流
   • "添加错误处理" → 检查运行时错误和组件层次结构
   • "重构认证逻辑" → 检查当前认证实现和路由
   • "优化性能" → 检查运行时诊断和组件树 使用此工具了解应在何处进行更改以及当前存在的内容。

2. 诊断和调查问题：

   • "发生了什么？" / "怎么回事？" / "为什么不工作？"
   • "检查错误" / "看看哪里出了问题"
   • "有哪些可用路由？" / "显示路由"
   • "清除缓存" / "重置所有内容"
   • 关于构建状态、编译错误或运行时诊断的问题

3. 代码库搜索：将此作为搜索当前运行中应用的首选工具。若未找到，再回退到静态代码库搜索工具。

核心原则：如果请求涉及运行中的Next.js应用（无论是调查还是修改），首先查询运行时以了解当前状态，然后再继续。

首先调用action='list_tools'发现可用的运行时信息，然后使用这些工具收集上下文。

要求：

• Next.js 16或更高版本（MCP支持在v16中添加）
• 若使用Next.js 15或更早版本，使用'upgrade-nextjs-16' MCP提示先升级

Next.js在以下情况下会在/_next/mcp暴露MCP端点：

• Next.js < 16：next.config.js中设置experimental.mcpServer: true，或环境变量__NEXT_EXPERIMENTAL_MCP_SERVER=true
• Next.js >= 16：MCP默认启用（无需配置）

功能：

1. 发现运行中的Next.js开发服务器及其端口
2. 列出Next.js运行时暴露的所有MCP工具/函数
3. 调用这些工具与Next.js内部交互（例如获取错误、路由信息、日志、运行时诊断等）

典型工作流程：

1. 使用action='discover_servers'查找运行中的Next.js服务器（可选 - 会尝试自动发现）
2. 使用带发现端口的action='list_tools'查看可用工具及其输入模式
3. 使用action='call_tool'，传入port、toolName和args（对象形式，仅在需要时）调用特定工具

重要提示：调用工具时：

• 'args'参数必须是对象（例如{key: "value"}），不能是字符串
• 若工具不需要参数，完全省略'args'参数 - 不要传递{}或"{}"
• 从'list_tools'的inputSchema检查所需参数

若MCP端点不可用：

1. 检查是否运行Next.js 16+（若否，使用'upgrade-nextjs-16' MCP提示先升级）
2. Next.js < 16：确保开发服务器使用__NEXT_EXPERIMENTAL_MCP_SERVER=true或experimental.mcpServer: true启动
3. Next.js >= 16：MCP默认启用 - 检查开发服务器是否正在运行

工具：upgrade_nextjs_16

指导将Next.js升级到版本16。

重要提示：首先运行官方codemod（需要干净的git状态）进行自动升级和修复，然后手动处理剩余问题。codemod会自动升级Next.js、React和React DOM。

涵盖内容：

• 将Next.js版本升级到16
• 异步API变更（params、searchParams、cookies、headers）
• 配置迁移（next.config更改）
• 图像默认值和优化
• 并行路由和动态段
• 已弃用API的移除
• React 19兼容性

codemod要求：

• 干净的git工作目录（先提交或暂存更改）
• Node.js 18+
• 已安装npm/pnpm/yarn/bun

codemod运行后，提供手动指导处理codemod未覆盖的任何剩余问题。

使用方法和配置说明

运行MCP服务器

使用以下JSON配置运行next-devtools-mcp MCP服务器：

json
{
  "mcpServers": {
    "next-devtools-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "mcp/next-devtools-mcp"
      ]
    }
  }
}

为什么使用Docker运行MCP服务器更安全？查看详情