Claude Media
Next.js MCPサーバーをClaude Codeで使う設定ガイド
Claude CodeMCPチュートリアル

Next.js MCPサーバーをClaude Codeで使う設定ガイド

Next.js公式のnext-devtools-mcpをClaude Codeに接続し、next-dev-loopスキルで編集と検証を自動化する手順をまとめます。

読了目安 約11分

Next.js 16はnext-devtools-mcpというMCPサーバーを公式で提供しており、Claude Codeから実行中の開発サーバーへ直接アクセスできます。ビルドエラーやルート情報をターミナルの出力から読み解く必要がなく、.mcp.jsonへの追加とnext devの起動だけで接続できます。設定手順と、変更のたびに動作を自動検証するnext-dev-loopスキルの組み込み方をまとめます。MCPサーバー追加の一般的な流れはClaude Code MCP設定ガイドで扱っており、ここではNext.js固有の設定に絞ります。

Next.js MCPサーバー(next-devtools-mcp)とは

next-devtools-mcpは、実行中のNext.js開発サーバーの内部状態をClaude Codeに公開する公式npmパッケージです。Next.js 16以降のdevサーバーは/_next/mcpというHTTPエンドポイントを内蔵しており、next-devtools-mcpはそこへ接続してツールを中継します。

ビルドエラー・ルート一覧・Server Actionsの実装場所・コンパイル結果まで、ターミナルを目視で追わなくても直接取得できるのが特徴です。動作にはNext.js 16以上が必須で、パッケージ自体はNext.js本体とは別にnpx経由でインストールします。似た設計の公式MCPサーバーにはChrome DevTools MCPがあり、こちらはブラウザ側の計測に特化しています。next-devtools-mcpはあくまでNext.jsのサーバー内部を見る役割です。

ステップ1: .mcp.jsonにnext-devtools-mcpを追加する

プロジェクトルートの.mcp.jsonに、次の設定を追加します。既存のMCPサーバー設定がある場合はmcpServersオブジェクトの中に追記します。設定の書き方自体はContext7のMCPをClaude Codeに設定する手順と同じ.mcp.json形式です。

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

CLIから追加する場合はclaude mcp addでも同じ設定を書き込めます。

claude mcp add --transport stdio next-devtools --scope project \
  -- npx -y next-devtools-mcp@latest

--scope projectを付けると.mcp.jsonに書き込まれ、チームで共有できます。付けない場合は自分専用の~/.claude.jsonに保存され、他のメンバーには反映されません。同じ名前のサーバーをlocalスコープでもすでに定義していると、Claude Codeはlocalスコープの定義を優先するため、.mcp.jsonに足した設定が反映されない場合があります。反映されないときはclaude mcp listで重複を確認します。

ステップ2: 開発サーバーを起動して承認する

next devで開発サーバーを起動すると、next-devtools-mcpが稼働中のNext.jsインスタンスを自動的に検出して接続します。

npm run dev

Claude Codeは対話セッションで、.mcp.json由来のプロジェクトスコープサーバーを初回接続前に承認させる仕組みを持っています。claude mcp listを実行すると⏸ Pending approval (run \claude` to approve)と表示され、対話モードでclaudeを起動すると承認ダイアログが出ます。承認済みかどうかはclaude mcp get next-devtoolsでも個別に確認できます。過去に拒否した承認を選び直したいときはclaude mcp reset-project-choices`で選択をリセットできます。

ステップ3: 使えるツールを確認する

next-devtools-mcpは次の8つのツールを公開します。

ツールできること
get_errorsできることビルドエラー・ランタイムエラー・型エラーを取得
get_logsできることブラウザコンソールログとサーバー出力のログファイルパスを取得
get_page_metadataできること特定ページのルート・コンポーネント・レンダリング情報を取得
get_project_metadataできることプロジェクト構成・設定・開発サーバーURLを取得
get_routesできることファイルシステムからルート一覧を取得(appRouter/pagesRouter別)
get_server_action_by_idできることServer ActionsのIDから実装元のファイルと関数名を特定
get_compilation_issuesできることプロジェクト全体のコンパイル警告・エラーを取得(Turbopack限定)
compile_routeできること指定ルートをHTTPリクエストなしでオンデマンドコンパイル(Turbopack限定)

get_compilation_issuesとcompile_routeはTurbopackでのみ動作します。Webpackビルドのプロジェクトではこの2つを呼び出せません。ツール数自体は8個と少なく、MCPのツール定義がコンテキストを圧迫する問題が起きやすい多機能サーバーとは事情が異なります。

8つのツールに加えて、next-devtools-mcpは「Documentation Gateway」としてインストール済みNext.jsのバージョンに一致するバンドル版docsへの経路も提供します。生成コードの説明が、実際に動いているバージョンとずれる事故を防ぐ役割です。ブラウザでの見た目を確認する用途には、別途Playwright MCPとの連携が用意されています。

実際の使い方

エラー調査は自然文で聞くだけで完結します。

今出ているエラーを直して

Claude Codeはnext-devtools-mcp経由でget_errorsを呼び出し、ハイドレーションエラーのようなブラウザ起因の問題も、発生ページと原因を特定したうえで修正に入ります。next buildを都度実行して結果を待つ手順を省けます。バージョンアップの相談にも使えます。

Next.js 16にアップグレードして

この指示に対しては、公式のアップグレードcodemod(npx @next/codemod@latest upgrade latest)を実行したうえで、破壊的変更への対応を案内する動きになります。

next-dev-loopスキルで編集と検証のループを作る

next-devtools-mcpが渡すのはNext.js側の視点だけです。編集のたびに実際の画面やコンソールも確認したい場合は、Vercelが公式に配布するnext-dev-loopスキルを追加します。

next-dev-loopは/_next/mcp(フレームワークの視点)とagent-browserというCLI(ブラウザの視点)を組み合わせ、コードを編集するたびに実際に動いているかをClaude Code自身が確認できるようにします。動作にはNext.js 16.3以上とTurbopack、agent-browser 0.31.1以上が必要です。

npx skills add vercel/next.js --skill next-dev-loop

インストール先はプロジェクトで使っているエージェントを自動検出して選ばれ、Claude Codeが検出されれば.claude/skills/配下にSKILL.mdとして追加されます。導入後は次のように指示すると、編集後の検証を自動化できます。

編集するたびに、next-dev-loopスキルでランタイムの動作を検証して

agent-browserのインストールが別途必要な点には注意が必要です。npm i -g agent-browser@latestでグローバルインストールしておかないと、スキル側が起動時に案内を出して停止します。

AGENTS.mdとCLAUDE.mdの優先順位に注意

Next.js 16.3以降でnext devを実行すると、AGENTS.mdとCLAUDE.mdが自動生成されます。生成されるCLAUDE.mdの中身は@AGENTS.mdという1行のインポート文だけで、実体の指示はすべてAGENTS.md側に書かれます。新規プロジェクトの場合はcreate-next-app@canaryが同じ2ファイルを作成時点で用意し、不要なら--no-agents-mdを付けて生成そのものを省けます。

この構成は、Claude Codeが同じディレクトリにCLAUDE.mdとAGENTS.mdの両方がある場合、既定ではCLAUDE.mdだけを読みAGENTS.mdを読み込まない仕様を踏まえたものです。AGENTS.mdを単独で読む設定はClaude Code v2.1.277以降が対象で、Amazon Bedrock経由のセッションやtelemetryを無効化した環境では直接読めない制約もあります。Next.jsがCLAUDE.md側に@AGENTS.mdのインポート文を書いておくことで、Claude Codeを含むどのエージェントでも同じAGENTS.mdの内容が確実に読み込まれる形にしています。

プロジェクト側で独自のCLAUDE.mdをすでに運用している場合は、Next.jsが書き込む管理ブロックを削除せず外側に追記すれば、自動生成分と自分の指示を両立できます。AGENTS.mdとCLAUDE.mdの自動生成そのものが不要な場合は、next.config.tsでagentRulesをfalseに設定すると止められます。

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  agentRules: false,
}
 
export default nextConfig

バンドルされたdocsはnode_modulesを直接読む以外に、ネットワーク越しでも参照できます。nextjs.org/docs配下のURL末尾に.mdを付けるとMarkdown版が返り、/docs/llms.txtは全docsの索引としてllms.txt規格に沿った形で公開されています。node_modulesを読めない環境でエージェントに公式docsを渡したいときに使えます。

よくあるつまずき

next-devtools-mcpがそもそも接続されない

公式のトラブルシューティングでは4点の確認が案内されています。Next.js v16以上を使っているか、.mcp.jsonにnext-devtools-mcpが正しく設定されているか、npm run devで開発サーバーを起動しているか、そしてすでに起動していた場合は開発サーバーを再起動したかです。これらを満たしたうえで、Claude Code側がMCP設定を読み込んでいるかも確認します。

Next.js 16.2以前では自動生成されない

バージョン16.2ではdocsがnode_modules/next/dist/docs/にバンドルされていますが、AGENTS.mdの自動生成は動きません。手動で同ディレクトリを読むよう指示するファイルを作成します。16.1以前はdocsのバンドル自体がなく、npx @next/codemod@canary agents-mdでバージョン一致のコピーを.next-docs/にダウンロードして使う必要があります。

承認待ちのまま接続されない

claude mcp listで⏸ Pending approvalのまま止まっている場合、対話モードでclaudeを一度起動して承認する必要があります。ヘッドレス実行だけで運用していると承認プロンプト自体が出ないので、.mcp.jsonへの追加直後に一度対話セッションを開くのが確実です。

Turbopack以外ではコンパイル系ツールが使えない

get_compilation_issuesとcompile_routeはTurbopack限定の機能です。Webpackでビルドしているプロジェクトでこれらを呼び出すと、next-dev-loopスキルの実装では"Turbopack project is not available..."というエラーが返る旨が案内されており、これが出たらWebpack構成のままである合図として扱えます。

まとめ

next-devtools-mcpは.mcp.jsonへの数行の追加とNext.js 16以上の要件だけで、Claude Codeにdevサーバーの内部状態を渡せる公式MCPサーバーです。get_errorsやget_routesのようなツールで手作業のログ確認を省け、next-dev-loopスキルを重ねればブラウザ側の見た目まで含めた検証ループを組めます。AGENTS.mdとCLAUDE.mdが両方生成される理由も、Claude Code側の読み込み優先順位を知っておくと導入時に迷いません。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →