Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp 是一個模型上下文協定 (Model Context Protocol, MCP) 伺服器，可將 Claude 和 Cursor 等編碼代理連接到您正在執行的 Next.js 開發伺服器。

它是一個輕量連接器。它會偵測正在執行的 Next.js 16+ 開發伺服器，並代理其內建的 MCP 端點 (/_next/mcp)，讓代理能夠取得即時的執行階段錯誤、路由和日誌。它還提供兩個閘道，引導代理直接執行工具：版本精確的文件和 agent-browser CLI。

[!NOTE] 文件和遷移工作流程已不再存在於此伺服器中。Next.js 將其自身的文件捆綁在 node_modules/next/dist/docs/，而升級／快取元件工作流程則以代理技能的形式分發。請參閱從 0.3.x 遷移。

需求

• Node.js v20.19 或更新的 LTS 版本
• npm 或 pnpm
• Next.js 16+ 且開發伺服器正在執行（用於 nextjs_index / nextjs_call）

安裝

使用 add-mcp 為所有編碼代理安裝：

npx add-mcp next-devtools-mcp@latest

加入 -y 可跳過提示並安裝到所有偵測到的代理。加入 -g 可在所有專案中全域安裝。

或手動將設定新增至您的 MCP 客戶端：

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

[!NOTE] next-devtools-mcp@latest 可讓您的客戶端保持在最新版本。

客戶端專屬設定

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

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

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

env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

# Project
gemini mcp add next-devtools npx next-devtools-mcp@latest

# Global
gemini mcp add -s user next-devtools npx next-devtools-mcp@latest

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

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

快速入門

啟動您的 Next.js 開發伺服器：

npm run dev

Next.js 16+ 預設會在 http://localhost:3000/_next/mcp 啟用其 MCP 端點。next-devtools-mcp 會自動偵測並連接到它 — 無需設定。

然後向您的代理詢問正在執行的應用程式：

Next Devtools, what errors are in my Next.js application?
Next Devtools, show me the structure of my routes
Next Devtools, what's in the development server logs?

代理會呼叫 nextjs_index 來偵測伺服器，然後呼叫 nextjs_call 來查詢它們的實際狀態。

工具

閘道本身不執行工作 — 它們會告訴代理文件在哪裡，或如何安裝／執行 CLI，然後由代理直接執行（比透過 MCP 代理更快）。

{ "port": 3000, "toolName": "get_errors" }

從 0.3.x 遷移

從 0.4.0 開始，next-devtools-mcp 是一個輕量連接器。

已變更：

• nextjs_docs 不再透過網路擷取文件。它會引導代理取得 Next.js 捆綁在 node_modules/next/dist/docs/ 的文件（或建議升級）。nextjs-docs://llms-index 資源已移除。

已移除：

• init 工具 — 它僅強制執行舊的文件擷取工作流程。
• upgrade_nextjs_16 和 enable_cache_components 工具及其提示 — 現在以代理技能的形式分發。
• 所有 cache-components://、nextjs16:// 和 nextjs-fundamentals:// 資源 — 已被捆綁的文件取代。

保留項目：nextjs_index、nextjs_call、nextjs_docs 和 browser_eval。

隱私權與遙測

next-devtools-mcp 會收集匿名的使用遙測資料以改善工具：

• 工具使用情況 — 調用了哪些 MCP 工具（例如 nextjs_index、nextjs_call）
• 錯誤事件 — 工具失敗時的匿名錯誤訊息
• 工作階段中繼資料 — 工作階段 ID、時間戳記、基本環境（作業系統、Node.js 版本）

不收集的資料： 您的程式碼、檔案內容或路徑、個人資料、憑證或工具參數（僅工具名稱）。

本機檔案存放在 ~/.next-devtools-mcp/ 下（匿名 telemetry-id、telemetry-salt 和偵錯日誌 mcp.log）。

退出 可設定環境變數（將其新增至 ~/.zshrc / ~/.bashrc 以持續生效）：

export NEXT_TELEMETRY_DISABLED=1

隨時刪除本機遙測資料：

rm -rf ~/.next-devtools-mcp

疑難排解

ERR_MODULE_NOT_FOUND 參照 next-devtools-mcp/dist — 清除您的 npx 快取並重新啟動 MCP 客戶端。伺服器會全新重新安裝。

[error] No server info found — nextjs_index / nextjs_call 需要一個正在執行的 Next.js 16+ 開發伺服器：

1. 啟動它：npm run dev
2. 確認 Next.js 16+（/_next/mcp 端點僅存在於此版本）
3. 驗證它已啟動且無錯誤

browser_eval 和 nextjs_docs 無需開發伺服器即可運作。

本機開發

git clone https://github.com/vercel/next-devtools-mcp.git
cd next-devtools-mcp
pnpm install
pnpm build

將您的 MCP 客戶端指向本機建置：

{
  "mcpServers": {
    "next-devtools": {
      "command": "node",
      "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"]
    }
  }
}

或使用 Codex：

codex mcp add next-devtools-local -- node dist/index.js

請參閱 Next.js MCP 文件，了解 MCP 如何與 Next.js 和編碼代理搭配運作。

授權

MIT