--- title: "Next.js DevTools MCPの使い方｜next-devtools-mcp 0.4の設定と/_next/mcpの9ツール" url: "https://www.issoh.co.jp/tech/details/9941/" published: 2025-11-21 updated: 2026-10-03 categories: ["Next.js"] publisher: "株式会社一創" --- # Next.js DevTools MCPの使い方｜next-devtools-mcp 0.4の設定と/\_next/mcpの9ツール Next.js DevTools MCPは、Claude CodeやCursorなどのコーディングエージェントを、手元で動いている`next dev`につなぐ仕組みです。Next.js 16以降の開発サーバーには`/_next/mcp`というMCPエンドポイントが組み込まれており、npmパッケージの`next-devtools-mcp`がエージェントとの間を中継します。エージェントは、ビルドエラーやルート一覧、開発ログを推測ではなく実行中のサーバーから取得できます。 このパッケージは2026年6月24日の0.4.0で作り直され、`upgrade_nextjs_16`や`enable_cache_components`といったツールは削除されました。2025年に書かれた解説の多くは0.3系が前提です。この記事では、2026年10月3日にmacOS x86\_64・Node.js v26.5.0でnext-devtools-mcp 0.4.0とNext.js 16.3.8（Turbopack）を動かして確認した結果をもとに、設定方法と使えるツールを説明します。Next.jsの版ごとの変更点は[Next.js 16の最新バージョンとリリース履歴](/tech/details/9596/)にまとめています。 ## まとめ：next-devtools-mcp 0.4とNext.js 16.3の要点 - 設定は`.mcp.json`に`npx -y next-devtools-mcp@latest`を書くだけです。動いている開発サーバーは自動で検出されます。 - 0.4.0のツールは`nextjs_index`・`nextjs_call`・`nextjs_docs`・`browser_eval`の4つです。エラーやルートの取得は、開発サーバー側の`/_next/mcp`が担います。 - Next.js 16.3.8の`/_next/mcp`には9つのランタイムツールがあります。16.0.0の時点では5つでした。`compile_route`などコンパイルを確かめるツールは16.3で増えています。 - Next.js 16へのアップグレードは`npx @next/codemod@latest upgrade latest`で行います。Cache Componentsへの移行はNext.js公式のAgent Skillsに移りました。 - `/_next/mcp`は`next dev`にしか存在せず、`next start`では404になります。ただし既定の`next dev`ではLAN内の別の端末からも届くため、共有ネットワークでは`-H 127.0.0.1`で起動してください。 ## next-devtools-mcpと/\_next/mcpの二層構造 実際にアプリの状態を返しているのは、Next.js本体に組み込まれた`/_next/mcp`です。`next dev`の中で動き、HTTP経由でMCPのリクエストを受け付けます。`next-devtools-mcp`はエージェントが標準入出力で起動するMCPサーバーで、開発サーバーを探して`/_next/mcp`へ呼び出しを転送します。READMEはこれを「thin connector（薄い中継役）」と表現しています。 中継役がいるため、ポートの異なる複数のNext.jsプロジェクトを1つの設定で扱えます。MCPの仕組みそのものは[MCP（Model Context Protocol）の仕組みの解説](/tech/details/5736/)を参照してください。 ### 0.4.0に残った4つのツール | ツール | 役割 | 開発サーバー | | ------------- | ----------------------- | ------ | | nextjs\_index | 開発サーバーを探し、使えるツールを列挙 | 必要 | | nextjs\_call | 指定したポートのランタイムツールを実行 | 必要 | | nextjs\_docs | 同梱ドキュメントの場所を案内 | 不要 | | browser\_eval | agent-browserの導入と使い方を案内 | 不要 | `nextjs_docs`と`browser_eval`は、READMEで「Gateway」と位置づけられています。どちらも自分では処理をせず、エージェントがシェルで実行するための手順を返します。`nextjs_docs`が案内する先は`node_modules/next/dist/docs/`で、インストール済みのNext.jsと同じ版のドキュメントがMarkdownで入っています。0.4.0を標準入出力で起動して確認したところ、`prompts/list`と`resources/list`はどちらも「Method not found」を返しました。ツール以外の機能は持っていません。 ### 0.3系から削除された機能と移行先 | 0.3系の機能 | 0.4.0での扱い | 移行先 | | ------------------------------- | ------------------- | ----------------------------- | | init | 削除 | 不要 | | upgrade\_nextjs\_16 | 削除 | @next/codemod の upgrade | | enable\_cache\_components | 削除 | Next.js公式のAgent Skills | | nextjs\_docs のネット取得 | 同梱ドキュメントの案内に変更 | node\_modules/next/dist/docs/ | | browser\_eval のPlaywright MCP中継 | agent-browserの案内に変更 | agent-browser CLI | Cache Componentsへの移行は、vercel/next.jsリポジトリの`skills/`にある`next-cache-components-adoption`（段階的な有効化）と`next-cache-components-optimizer`（特定ルートの高速化）が担います。どちらも`npx skills add vercel/next.js --skill <名前>`で入れます。以前のvercel-labs/next-skillsリポジトリは移転を告知しており、そこにあった`next-upgrade`は廃止されました。Skillsの仕様は[Agent Skillsの仕様と導入手順](/tech/details/17685/)で解説しています。 注意点として、Next.js公式ドキュメントのMCPガイド（2026年10月時点で最終更新は2026年7月8日）には、ブラウザ検証の手段として「Playwright MCP integration」と書かれたままです。0.4.0のリリースノートは`browser_eval`が「no longer proxies @playwright/mcp」と明記しており、同梱のソースもagent-browserを案内しています。挙動の確認はパッケージ側の[README](https://github.com/vercel/next-devtools-mcp/tree/v0.4.0)と[リリースノート](https://github.com/vercel/next-devtools-mcp/releases/tag/v0.4.0)を優先してください。agent-browserについては[agent-browserの使い方とインストール](/tech/details/10588/)にまとめています。 ## Claude Code・Cursor・Codexへの導入手順 ### 前提条件：Node.js 20.19以上とNext.js 16以上 READMEが求める環境は、Node.js v20.19以上、npmまたはpnpm、そしてランタイムツールを使う場合はNext.js 16以上の開発サーバーです。Next.js 16.3.8自体は`engines.node`が`>=20.9.0`なので、Node.jsは20.19以上に合わせておけば両方を満たします。Next.js 15以前には`/_next/mcp`がなく（15.5.0の設定項目に`mcpServer`は存在しません）、`nextjs_index`は何も見つけられません。 ### 設定ファイルとクライアント別のコマンド プロジェクト直下の`.mcp.json`に次の内容を書くのが、Next.js公式ガイドの手順です。 ``` { "mcpServers": { "next-devtools": { "command": "npx", "args": ["-y", "next-devtools-mcp@latest"] } } } ``` クライアントごとのコマンドで登録することもできます。READMEに載っているものは次のとおりです。 ``` # Claude Code claude mcp add next-devtools npx next-devtools-mcp@latest # Codex codex mcp add next-devtools -- npx next-devtools-mcp@latest # VS Code（GitHub Copilot） code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}' # 対話形式で登録先のエージェントを選択 npx add-mcp next-devtools-mcp@latest ``` Cursorは「Cursor Settings」の「MCP」から「New MCP Server」を選び、上の設定を貼り付けます。Windows 11のCodexでは、`.codex/config.toml`に`SystemRoot`と`PROGRAMFILES`の環境変数を渡し、`startup_timeout_ms = 20_000`を設定するようREADMEが求めています。Claude Code側のMCP設定の置き場所は[Claude Codeの使い方と設定](/tech/details/17375/)で確認できます。 ### 接続の確認：nextjs\_indexの応答 `npm run dev`で開発サーバーを起動し、エージェントに「Next.jsアプリのエラーを確認して」のように頼みます。エージェントはまず`nextjs_index`でサーバーを探し、続けて`nextjs_call`でランタイムツールを呼びます。Next.js 16.3.8で`nextjs_index`を実行すると、次の形の応答が返りました（ツールの説明文は省略）。 ``` {"success":true,"count":1,"servers":[{"port":3456,"pid":30921, "command":"next-server (v16.3.8)","url":"http://localhost:3456", "toolCount":9,"tools":[{"name":"get_project_metadata", ...}]}]} ``` 検証したNext.js 16.3.8のTurbopack環境では、`toolCount`は9でした。ツール数だけでは版を特定できないため、バージョンは`npx next --version`で確認してください。`success`が`false`で、`servers`が空の配列の場合は、後述の確認手順に進んでください。 ## /\_next/mcpのランタイムツール9種（Next.js 16.3.8） Next.js 16.3.8のTurbopack開発サーバーに`tools/list`を送って得た一覧です。webpackではコンパイル関連の2ツールが登録されないため、一覧は7件になります。Next.js公式のMCPガイドに載っているのは8つで、`get_request_insights`はガイドに記載がありません。 | ツール | 返すもの | 引数 | 追加された版 | | --------------------------- | ----------------------------- | --------------------- | ------ | | get\_project\_metadata | プロジェクトのパスと開発サーバーのURL | なし | 16.0 | | get\_errors | ビルド・ランタイム・設定のエラー | なし | 16.0 | | get\_page\_metadata | 表示中ページの構成要素 | なし | 16.0 | | get\_logs | 開発ログファイルのパス | なし | 16.0 | | get\_server\_action\_by\_id | Server Actionのファイルとexport名 | actionId | 16.0 | | get\_routes | App Router・Pages Routerのルート一覧 | routerType | 16.1 | | get\_compilation\_issues | 全ルートのコンパイル問題 | なし | 16.3 | | compile\_route | 指定ルートだけをコンパイルした結果 | routeSpecifier / path | 16.3 | | get\_request\_insights | リクエストごとの処理の内訳 | requestId など | 16.3 | 追加された版は、npmで配布されている16.0.0・16.1.0・16.2.0・16.3.0のソース（`get-or-create-mcp-server.js`）で、登録されているツールを比べて確かめました。16.2までは6つで、16.3.0で3つ増えています。 ### ランタイムツールの実応答と利用条件 最小構成のアプリ（`/`と`/blog/[slug]`の2ルート）で各ツールを呼ぶと、ドキュメントの一覧だけでは分からない制約が見えました。 - `get_errors`は、ブラウザでページを一度も開いていない状態だと「No browser sessions connected. Please open your application in a browser to retrieve error state.」を返します。ブラウザのランタイムエラーは、ブラウザ側の接続から集めているためです。 - `get_logs`が返すのはログの中身ではなく、`.next/dev/logs/next-development.log`というファイルのパスです。エージェントはそのファイルを自分で読みに行きます。 - `compile_route`に`path: "/blog/hello-world"`を渡すと、`routeSpecifier`が`/blog/[slug]`に解決され、問題がなければ`issues`が空の配列で返ります。HTTPリクエストを送らずに、そのルートがコンパイルできるかを確かめられます。 - `get_compilation_issues`と`compile_route`はTurbopack専用で、webpackでは一覧にも出ません。Turbopackへの切り替えは[Turbopackの設定と移行判断](/tech/details/16015/)を参照してください。 - `get_request_insights`は、`next.config.js`で`experimental.requestInsights = true`を設定して`next dev`を再起動しないと、有効になっていない旨のメッセージを返すだけです。 ### curlで/\_next/mcpを直接呼ぶ確認方法 エージェントがつながらないとき、原因がNext.js側か中継側かを切り分けるには、エンドポイントを直接呼ぶのが早道です。`Accept`ヘッダーに`application/json`と`text/event-stream`の両方を含めないPOSTには、HTTP 406のエラー応答が返ります。GETも、`Accept`に`text/event-stream`を含めない場合は406になります。 ``` curl -s -X POST http://localhost:3000/_next/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_routes","arguments":{}}}' ``` `event: message`に続いてルート一覧のJSONが返れば、Next.js側は正常です。この状態でエージェントからつながらない場合は、MCPクライアントの設定か`next-devtools-mcp`の起動を疑ってください。 ## エージェントに任せやすい作業と向かない作業 任せやすいのは、開発サーバーの状態を読めば答えが出る作業です。たとえばハイドレーションエラーの修正では、ブラウザでページを開いた状態で`get_errors`を呼ばせれば、ソースマップ済みのスタックトレースから原因の箇所に直行できます。ファイルを編集するたびに`compile_route`で対象ルートを確かめさせれば、`next build`を丸ごと回さずにコンパイルエラーを拾えます。エラーログにServer ActionのIDしか出ていないときは、`get_server_action_by_id`でファイル名とexport名を引けます。 一方、次の条件ではランタイムツールが使えないか、使える範囲が限られます。 - 本番環境の障害調査。`next build`のあと`next start`で起動したサーバーでは、`/_next/mcp`へのPOSTが404でした。本番の問題には、ログ基盤やAPMを使ってください。 - Next.js 15以前のプロジェクト。エンドポイントがないため、先に16以上へ上げる必要があります。 - ブラウザを開かないCIでの自動修正。`get_errors`はブラウザの接続がないとランタイムエラーを返しません。この用途では、ブラウザ不要の`get_compilation_issues`（Turbopack時のみ）を使うことになります。 ブラウザ上の見た目やDOMをエージェントに確かめさせたい場合は、`/_next/mcp`ではなくブラウザ側のツールが必要です。Next.js公式はagent-browserを推していますが、Chromeの開発者ツールを直接操作する[Chrome DevTools MCPの導入手順](/tech/details/17749/)も選択肢になります。 ## LANからの到達と無効化の設定 ### 既定のnext devの待受範囲とLAN経由のアクセス `next dev`は既定ですべてのネットワークインターフェースで待ち受けます。起動時に表示される「Network」のアドレス（検証環境では192.168.x.x）宛てに同じLAN内からPOSTしたところ、`tools/list`が200で返り、ツールを呼べる状態でした。`get_project_metadata`はプロジェクトの絶対パスを、`get_logs`はログファイルのパスを返します。 一方、`Origin: http://evil.example`を付けたリクエストは403で拒否されました。ブラウザ経由で外部サイトから呼ばれる経路は塞がれていますが、LAN内から直接送られるリクエストは止まりません。カフェや共有オフィスのWi-Fiで開発する場合は、待ち受けをローカルに限定して起動してください。 ``` npx next dev -H 127.0.0.1 ``` この設定にするとLAN IP宛ての接続は届かなくなり、`localhost`からの呼び出しは引き続き200で返りました。`next-devtools-mcp`は既定で`localhost`に接続するため（ソース上は環境変数`NEXT_DEVTOOLS_HOST`で変更可能）、3001番で起動したサーバーもそのまま検出できました。 ### エンドポイントを止める：experimental.mcpServer `/_next/mcp`は、Next.js 16.0.0以降、設定項目`experimental.mcpServer`の既定値が`true`のため自動で有効になります。不要なら`next.config.js`で止められます。 ``` module.exports = { experimental: { mcpServer: false }, }; ``` この設定で起動した開発サーバーでは、`/_next/mcp`へのPOSTが404になりました。 ### next-devtools-mcpのテレメトリ `next-devtools-mcp`は匿名の利用状況を送信します。READMEによると、送るのは呼ばれたツール名、エラーメッセージ、セッションIDやOSとNode.jsのバージョンで、コードやファイルパス、ツールの引数は含みません。止めるには環境変数`NEXT_TELEMETRY_DISABLED=1`を設定し、ローカルに残ったデータは`~/.next-devtools-mcp`を削除すれば消えます。 ## Next.js 16.3のAGENTS.md自動生成とSkillsの使い分け Next.js 16.3以降の`next dev`は、コーディングエージェントの環境を検知すると、プロジェクト直下に`AGENTS.md`と`CLAUDE.md`を生成します。Claude Codeの中で検証用アプリの`next dev`を起動したところ、2つのファイルが作られました。`AGENTS.md`には「This is NOT the Next.js you know」という見出しで、`node_modules/next/dist/docs/`を読んでからコードを書くよう指示する管理ブロックが入り、`CLAUDE.md`は`@AGENTS.md`の1行だけでした。このブロックは消しても`next dev`が書き戻すので、コミットしておくのが公式の推奨です。 フレームワークの知識は同梱ドキュメントと`AGENTS.md`、実行中の状態は`/_next/mcp`、複数の手順にまたがる作業はSkillsが担います。Skillsの中で`/_next/mcp`と最も関係が深いのは`next-dev-loop`で、編集のたびにMCPとブラウザで実行時の動作を確かめる手順をエージェントに持たせます。16.3で入ったほかの変更は[Next.js 16.3の新機能の解説](/tech/details/15608/)にまとめています。 ## next-devtools-mcpの接続失敗時の確認手順 1. `npx next --version`で16以上かを確かめます。15以前にはエンドポイントがありません。 2. 開発サーバーが起動しているかを確かめます。`nextjs_index`と`nextjs_call`は動いている`next dev`が必要です。READMEは、この状態で出るエラーを「\[error\] No server info found」と記載しています。 3. ポートを確認します。0.4.0は3000〜3010番を先に調べ、その結果にかかわらずプロセスから`next-server`も探し、重複するポートを除いて結果をまとめます。それでも見つからないときは、`nextjs_index`の`port`引数でポートを指定します。 4. 前述のcurlで`/_next/mcp`を直接呼びます。404なら`experimental.mcpServer: false`が設定されていないかを確かめます。 5. 「ERR\_MODULE\_NOT\_FOUND」で`next-devtools-mcp/dist`が見つからないと出る場合は、npxのキャッシュを消してMCPクライアントを再起動します。 6. `get_errors`が「No browser sessions connected」を返すときは、ブラウザでページを開いてから呼び直します。 GitHubのmainブランチには2026年9月15日にマージされた0.4.1の変更履歴がありますが、2026年10月3日時点のnpmの`latest`は0.4.0です。mainのREADMEは0.4.1が前提（`nextjs_index`は引数なし、など）なので、挙動が食い違うときは`npm view next-devtools-mcp version`で版を確かめてください。 ## よくある質問 ### next-devtools-mcpとChrome DevTools MCPの違いは？ next-devtools-mcpは、Next.jsの開発サーバーからエラー・ルート・ログなどフレームワーク内部の情報を取ります。Chrome DevTools MCPは、ブラウザを操作してDOMやネットワーク、パフォーマンスを調べます。前者はNext.js 16以上の`next dev`専用で、後者はフレームワークを問いません。 ### Next.js 15でもnext-devtools-mcpは使えますか？ ランタイムツールは使えません。`/_next/mcp`はNext.js 16.0.0で入ったためです。15以前では、`nextjs_docs`も`npx @next/codemod@latest upgrade latest`での更新を勧めるだけです。 ### 本番環境で/\_next/mcpは公開されますか？ 公開されません。`next start`で起動したサーバーでは404でした。注意が必要なのは開発中のLANからの到達で、`next dev -H 127.0.0.1`で待ち受けを限定できます。 ### upgrade\_nextjs\_16ツールが見つからないのはなぜですか？ 0.4.0で削除されたためです。`@latest`を指定していると自動で0.4系に上がります。アップグレードは`npx @next/codemod@latest upgrade latest`で行い、Cache Componentsの導入は`next-cache-components-adoption`スキルを使います。 ### next-devtools-mcpは無料ですか？ MITライセンスのオープンソースで、料金はかかりません。匿名のテレメトリを送信しますが、`NEXT_TELEMETRY_DISABLED=1`で止められます。 ## 関連記事 - [Next.js 16の最新バージョンは16.3｜リリース履歴・LTS方針・アップデート手順](/tech/details/9596/) - [Next.js 16.3とは？Turbopack永続キャッシュとInstant Navigationsなど新機能を実装者目線で解説](/tech/details/15608/) - [MCP（Model Context Protocol）とは？AIと外部ツールをつなぐ標準規格の仕組みをわかりやすく解説](/tech/details/5736/) - [Chrome DevTools MCPの導入手順と設定｜58ツールの絞り込みと接続方式を実装目線で解説](/tech/details/17749/) - [agent-browserとは｜Vercel製ブラウザ操作CLIの使い方・インストール・プロキシ設定](/tech/details/10588/) --- 出典: [Next.js DevTools MCPの使い方｜next-devtools-mcp 0.4の設定と/\_next/mcpの9ツール]()（株式会社一創）