/ 目录 / 演练场 / Next.js DevTools
← 全部服务器 ↗ GitHub
● 官方 vercel ⚡ 即开即用

Next.js DevTools

作者 vercel · vercel/next-devtools-mcp

Next.js DevTools MCP — 搜索官方文档、驱动浏览器进行 E2E 检查、诊断运行中的 dev server，以及自动升级到 Next 16。

由 Vercel / Next.js 团队维护的官方 MCP，专注于 Next.js 开发体验。搜索官方 Next.js 文档、提供进程内 browser_eval 进行测试、发现运行中的 next dev server（v16+）并调用其内置 MCP endpoint，以及运行 codemod 升级到 Next 16 并启用 Cache Components。

▶ 观看演示 📦 安装 💡 使用场景

为什么要用

核心特性

实时演示

实际使用效果

vercel.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "vercel": {
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "vercel": {
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "vercel": {
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "vercel": {
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "vercel",
      "command": "npx",
      "args": [
        "-y",
        "@vercel/next-devtools-mcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "vercel": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@vercel/next-devtools-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add vercel -- npx -y @vercel/next-devtools-mcp

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： Next.js DevTools

使用引导式 codemod 将 Next.js 项目升级到 v16

👤 使用 v14/v15 的 Next.js 工程师 ⏱ ~60 min advanced

何时使用： 你一直在延迟 Next 16 升级。你想要一个 agent 来驱动 codemod 并修复 async API 迁移。

前置条件
  • v14+ 的 Next.js 项目 — 检查 package.json
  • 干净的 git 工作树 — git status 显示干净 — 这样需要时可以回滚
步骤
  1. 运行升级工具
    在这个项目上运行 upgrade_nextjs_16。在应用前逐个讲解每个 codemod。✓ 已复制
    → 计划变更列表及预览 diff
  2. 修复 async API 调用位置
    codemod 后，构建项目。对于 cookies()/headers() 现在变成 async 导致的任何错误，修复调用位置以使用 await。✓ 已复制
    → 构建通过
  3. 启用 Cache Components
    运行 enable_cache_components。修复它报告的任何边界错误。✓ 已复制
    → Cache components 已启用，应用运行

结果： 一个工作正常的 Next 16 项目，启用了 Cache Components，在一次专注的会话中完成，而不是散落地搞一周。

注意事项
  • Codemod 无法修复自定义模式的 async 用法 — 在每个 codemod 步骤后运行构建；当 codemod 标记 'REVIEW' 注释时手动修复
  • 第三方库可能还不支持 Next 16 — 升级前检查包兼容性；固定任何破损的库并向上游报告问题
搭配使用： git

通过诊断 endpoint 调试运行中的 Next dev server

👤 使用 v16+ 的 Next.js 工程师 ⏱ ~20 min advanced

何时使用： 你的 next dev 在运行但有些不对劲（奇怪的水合、错误的渲染模式）。Next 16+ 通过 /_next/mcp 暴露运行时工具。

前置条件
  • 运行着 Next.js 16+ dev server — npm run dev
步骤
  1. 发现 server
    运行 nextjs_index 找到我本地的 Next dev server 并列出它们暴露的诊断工具。✓ 已复制
    → Port + 工具列表
  2. 调用诊断工具
    在 port <PORT> 上使用 nextjs_call 获取 /dashboard 的路由树和渲染模式。是 static、dynamic 还是 partial？✓ 已复制
    → 每条路由的渲染模式及解释
  3. 修复错误的渲染
    /dashboard 页面使用 cookies() 使其完全动态，而我想要部分预渲染。找到错误的导入并重构以隔离。✓ 已复制
    → 修复后渲染模式变为 partial

结果： 深入了解 Next 的渲染决策，而无需阅读 20 篇博文。

注意事项
  • Dev server 诊断与 prod 构建输出不同 — 始终用 next build 验证 — dev 模式有不同的默认值

获得 Next.js 问题的权威答案

👤 任何级别的 Next.js 开发者 ⏱ ~10 min beginner

何时使用： 你有关于 Next.js 行为的问题。你不想要 LLM 幻觉 — 你想要引用。

步骤
  1. 搜索文档
    使用 nextjs_docs 找到官方关于中间件 vs 路由处理程序用于认证的指导。返回匹配的部分。✓ 已复制
    → 引用的文档部分及 URL
  2. 用引用来回答
    仅基于这些部分，我应该在我的 Next 16 应用中为 JWT 验证使用哪个，为什么？包含文档 URL。✓ 已复制
    → 带有 URL 的有根据的答案
  3. 应用到我的代码
    浏览我在 middleware.ts 中的当前实现。它是否与文档的建议一致？✓ 已复制
    → 具体的差距列表

结果： 由文档支持的权威 Next.js 决策，而不是直觉。

注意事项
  • 文档在发布后的几周内滞后于最新版本 — 对于最前沿的功能，也要检查 Next.js RFC / 博文

在你的 Next.js 应用上运行 E2E 检查

👤 Next.js 工程师 ⏱ ~10 min intermediate

何时使用： 你刚做了一个更改。你想在提交前做一个快速烟雾测试。

步骤
  1. 导航和捕获
    使用 browser_eval 打开 http://localhost:3000/pricing。截图并捕获任何控制台错误。✓ 已复制
    → 截图 + 控制台摘要
  2. 点击关键路径
    点击 'Select Pro plan'，验证结账模态框打开并显示正确的价格。截图每一步。✓ 已复制
    → 每步的通过/失败
  3. 报告
    总结：ok / broken / suspicious。如果有任何失败，粘贴控制台错误。✓ 已复制
    → 发货或不发货的判决

结果： 嵌入在你的 dev 循环中的快速理智检查 — 不需要单独的 Playwright 运行器。

注意事项
  • browser_eval 是 Playwright-lite — 不是完整 E2E 套件的替代品 — 用于快速检查；保持真实的 Playwright 套件用于发布门
搭配使用： playwright

组合

与其他 MCP 搭配，撬动十倍杠杆

vercel + playwright

browser_eval 用于快速检查，Playwright 用于完整回归套件

使用 browser_eval 烟雾测试 /pricing。如果通过，在关键路径上运行 Playwright 套件。✓ 已复制
vercel + git

升级 Next，在每一步提交

运行 upgrade_nextjs_16。在每个 codemod 之后，用描述性消息提交 diff，这样如果出问题我们可以二分查找。✓ 已复制
vercel + sentry

升级后监控

将 Next 16 构建部署到暂存。监控 Sentry 24 小时并标记 async API 迁移引入的任何新错误。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
init 新对话中的第一个调用 free
nextjs_docs query 任何 Next.js 事实性问题 free
browser_eval actions (navigate, click, screenshot, etc.) 快速的 E2E 测试你的 dev server free (local browser)
nextjs_index 发现 Next 16+ dev server free
nextjs_call port, tool_name, args 调用 Next 16+ 运行时诊断 free
upgrade_nextjs_16 project_path 从 v14/15 升级到 v16 的路径 free
enable_cache_components project_path 在 v16 应用中打开 Cache Components free

成本与限制

运行它的成本

API 配额
免费 — 本地执行 + 文档搜索
每次调用 Token 数
文档返回可能很大；在搜索上设置限制
费用
免费
提示
每个会话运行一次 init 以便 agent 知道可用工具 — 省去随意试错

安全

权限、密钥、影响范围

凭据存储： 无 — 本地工具
数据出站： 文档搜索访问 vercel.com；browser_eval 跟随你导航的任何地方；遥测到 vercel（通过 NEXT_TELEMETRY_DISABLED 选择退出）

故障排查

常见错误与修复

nextjs_index 找不到 server

仅 Next.js 16+ dev server 暴露 /_next/mcp。先升级，或对旧版本使用 browser_eval。

验证： curl http://localhost:3000/_next/mcp
browser_eval 启动失败

Playwright 二进制文件缺失。运行一次 npx playwright install。

Codemod 留下文件处于半迁移状态

通过 git 回滚，然后一个接一个地运行 codemod 而不是一次性全部运行。在每个之间提交。

nextjs_docs 返回不相关的结果

将 Next.js 主版本添加到你的查询：'app router middleware in Next 16' 而不仅仅是 'middleware'。

替代方案

Next.js DevTools 对比其他方案

替代方案何时用它替代权衡
Playwright MCP你需要完整的 Playwright，而不是轻量级的 browser_eval更强大但没有 Next.js 特定的诊断或文档搜索
Cloud Run MCP你部署到 GCP，而不是 Vercel不同的托管模型；此 MCP 专注于 Next.js DX，而不是部署

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills