Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp 是一個模型上下文協定（MCP）伺服器，可將 Claude 和 Cursor 等編碼代理程式連接到你正在執行的 Next.js 開發伺服器。

它是一個輕量連接器。它會探索正在執行的 Next.js 16+ 開發伺服器，並代理其內建的 MCP 端點（/_next/mcp），讓代理程式取得即時的執行時期錯誤、路由和日誌。它也提供兩個閘道，將代理程式指向它們直接執行的工具：版本精確的文件和 agent-browser CLI。

[!NOTE] 文件和遷移工作流程不再位於此伺服器中。Next.js 在 node_modules/next/dist/docs/ 綁定了自己的文件，而升級 / Cache Components 工作流程則以代理程式技能的形式發布。請參閱 從 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