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の最新バージョンとリリース履歴にまとめています。

まとめ：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）の仕組みの解説を参照してください。

0.4.0に残った4つのツール

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系から削除された機能と移行先

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の仕様と導入手順で解説しています。

注意点として、Next.js公式ドキュメントのMCPガイド（2026年10月時点で最終更新は2026年7月8日）には、ブラウザ検証の手段として「Playwright MCP integration」と書かれたままです。0.4.0のリリースノートはbrowser_evalが「no longer proxies @playwright/mcp」と明記しており、同梱のソースもagent-browserを案内しています。挙動の確認はパッケージ側のREADMEとリリースノートを優先してください。agent-browserについてはagent-browserの使い方とインストールにまとめています。

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の使い方と設定で確認できます。

接続の確認：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はガイドに記載がありません。

追加された版は、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の設定と移行判断を参照してください。
• 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の導入手順も選択肢になります。

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の新機能の解説にまとめています。

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方針・アップデート手順
• Next.js 16.3とは？Turbopack永続キャッシュとInstant Navigationsなど新機能を実装者目線で解説
• MCP（Model Context Protocol）とは？AIと外部ツールをつなぐ標準規格の仕組みをわかりやすく解説
• Chrome DevTools MCPの導入手順と設定｜58ツールの絞り込みと接続方式を実装目線で解説
• agent-browserとは｜Vercel製ブラウザ操作CLIの使い方・インストール・プロキシ設定