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

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

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

読了目安 約16分

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

設定の無いプロジェクトで実行すると、次の表示になります(v2.1.289)。

Added stdio MCP server next-devtools with command: npx -y next-devtools-mcp@latest to project config
File modified: /path/to/project/.mcp.json

生成された.mcp.jsonは、公式ガイドの最小形に"type": "stdio"と"env": {}が加わった形です。この2つは既定値を明示した記述にあたります。

--helpの表示では、--scopeの既定値はlocalです。--scope projectを付けないと.mcp.jsonには書かれず、他のメンバーに共有されません。

同じ名前のサーバーが複数のスコープにあると、Claude Codeは優先順位の高い定義を1つだけ使います。順位はlocal、project、userの順で、エントリは項目ごとに合成されず丸ごと置き換わります。localに同名の古い定義が残っていると、.mcp.jsonに足した設定は効きません。

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

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

npm run dev

.mcp.json由来のサーバーは、対話セッションで承認するまで接続されません。追加直後の表示は次のとおりです。

$ claude mcp list
next-devtools: npx -y next-devtools-mcp@latest - ⏸ Pending approval (run `claude` to approve)
 
$ claude mcp get next-devtools
next-devtools:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: stdio
  Command: npx
  Args: -y next-devtools-mcp@latest

listもgetも、承認前のサーバーには接続せずPending approvalと表示します。対話モードでclaudeを起動すると承認ダイアログが出ます。過去の承認や拒否をやり直したいときはclaude mcp reset-project-choicesでリセットします。

v2.1.196以降は、リポジトリにコミットされた設定ファイルの承認が、ワークスペースの信頼ダイアログを通すまで無視されます。クローンしたリポジトリが自分で自分のサーバーを承認する経路は塞がれています。

ステップ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との連携が用意されています。

実際の使い方

get_errorsとget_page_metadataは、ブラウザでページを一度開いてから呼ぶと結果が埋まります。ルート一覧のget_routesはファイルシステムの走査なので、ブラウザを開かなくても返ります。

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

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

Claude Codeはnext-devtools-mcp経由でget_errorsを呼び出し、ハイドレーションエラーのようなブラウザ起因の問題も、発生ページと原因を特定したうえで修正に入ります。ビルドを待たずに、実行中のサーバーから現在のエラーを取れます。バージョンアップの相談にも使えます。

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は2つの視点を突き合わせて検証します。動作にはNext.js 16.3以上とTurbopack、agent-browser 0.31.1以上が必要です。

くらべる

next-dev-loopが使う2つの視点

/_next/mcp

フレームワークの視点

ルート、サーバーログ、Next.jsが捉えたエラー、Server Actionsを返します。コンパイルが通るかもget_compilation_issuesでビルドなしに分かります。

agent-browser

ブラウザの視点

実際のChromeを操作するCLIです。DOM、コンソール、ネットワーク、Web Vitalsを構造化テキストで返し、React DevToolsを有効にするとコンポーネントツリーも読めます。

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で入れておかないと、スキルは案内を出して止まります。

スキルはセッションの最初に、次の順で両方の視点が生きているかを確かめます。

手順

next-dev-loopの事前チェック

  1. 1

    agent-browserでURLを開く

    セッションIDを固定し、--enable react-devtoolsを付けて開発サーバーのURLを開きます。

  2. 2

    /_next/mcpに接続できるか調べる

    tools/listが返り、get_compilation_issuesが含まれていれば16.3以上です。つながらなければ、devサーバーが未起動か16.3未満かをpackage.jsonで見分けて中断します。ツールが無ければ、アップグレードを案内して中断します。

  3. 3

    Turbopackで動いているか調べる

    get_compilation_issuesの応答が"Turbopack project is not available..."ならWebpack構成です。スキルはそこで中断します。

  4. 4

    get_routesでルート地図を取る

    以降の検証は、このルート一覧を前提に進みます。

編集前には、実行中のアプリに「このルートを描画しているファイルはどれか」を尋ねて検索範囲を絞ります。編集後は、コンパイル、実行時エラー、見た目、Reactレベルの挙動の4点を確かめます。

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

Next.js 16.3以降のnext devは、環境にAIコーディングエージェントが検出され、管理ブロックがまだ無いときに、AGENTS.mdとCLAUDE.mdをプロジェクトルートへ生成します。既存のファイルがあれば管理ブロックだけが追記・更新され、ブロックの外の内容は保たれます。

生成されるCLAUDE.mdは@AGENTS.mdという1行のインポート文だけで、実体の指示はAGENTS.md側にあります。新規プロジェクトではcreate-next-app@canaryが同じ2ファイルを作成時点で用意し、不要なら--no-agents-mdで省けます。

この構成はClaude Codeの読み込み規則に合わせたものです。

読み込み規則

Claude CodeがAGENTS.mdを読む条件

  • AGENTS.mdだけがある

    作業ディレクトリとその上位にCLAUDE.mdもCLAUDE.local.mdも無ければ、AGENTS.mdを読みます。

  • CLAUDE.mdかCLAUDE.local.mdもある

    既定ではCLAUDE.mdだけを読みます。AGENTS.mdは読まれません。CLAUDE.local.mdを追加した場合も、AGENTS.mdは自動では読まれなくなります。

  • CLAUDE.mdが@AGENTS.mdを取り込む

    AGENTS.mdの内容も入ります。Next.jsの自動生成はこの形で、取り込みを残しても二重には読まれません。

AGENTS.mdを直接読む機能はv2.1.277以降です。/pluginで組み込みのagents-mdプラグインを無効にしている場合は、CLAUDE.mdしか読まれません。v2.1.281より前は、Amazon Bedrock経由やtelemetryを無効にしたセッションでも直接読めませんでした。こうした環境ではCLAUDE.mdの@AGENTS.mdが確実な経路になります。v2.1.276以前からアップグレードした後の最初のセッションでも、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は、ネットワーク越しでも参照できます。nextjs.org/docs配下のURL末尾に.mdを付けるとMarkdown版が返り、Accept: text/markdownヘッダーを送るクライアントにもMarkdownが返ります。/docs/llms.txtが全docsの索引、/docs/llms-full.txtが1ファイル版です。

エラーごとの解説ページ(/docs/messages配下)はバンドルに含まれないため、エージェントがエラーメッセージのLearn moreリンクをたどるときはネットワーク経由になります。

開発サーバーがエージェント向けに出す情報

MCPを使わないエージェントでも、next devの出力から手がかりを得られます。

  • ブラウザのコンソールエラーと警告は、logging.browserToTerminalの設定でターミナルへ転送されます。クライアント側の失敗が、エージェントが読むターミナル出力に混ざります
  • next devは.next/dev/lockにPID・ポート・URLを書きます。同じプロジェクトで2つ目のnext devを起動すると、稼働中のURLと停止すべきPIDが表示され、重複起動を避けられます
  • Cache Componentsを有効にしたプロジェクトでは、ブロッキングエラーに[stream]・[cache]・[block]のラベル付き修正案が並びます。同じ表はnext buildの出力にも出るので、CIログを読むエージェントにも届きます

よくあるつまずき

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

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

開発サーバーのポートが3000以外のときは、next-dev-loopスキルを使う前にNEXT_MCP_URL=http://localhost:<port>/_next/mcpを設定します。ポートはnext devの起動バナーに出ています。

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を一度起動して承認します。手順はステップ2のとおりです。

next-dev-loopの検証が途中で食い違う

agent-browserが「ルートが壊れている」と報告するのに、/_next/mcpではきれいに描画されているときは、実アプリの不具合よりブラウザセッションの古さが疑われます。openの直後に空のスナップショットやabout:blankが返るのも同じ原因で、同じ起動フラグでセッションを開き直します。

開発サーバーの稼働中に.nextを移動・削除しないでください。生成済みの状態から切り離され、増分キャッシュも失われます。本番ビルドの出力を分けたいときは、別のdistDirを設定します。

/_next/mcpの応答はSSE形式です。コマンドラインで直接叩くなら、sed -n 's/^data: //p'でJSON行を取り出します。

まとめ

.mcp.jsonに数行足すだけで始められ、手元で試すならget_errorsから入れば効果が分かります。ブラウザ側の見た目まで検証したいときだけnext-dev-loopを足し、Next.js 16.3以上かつTurbopackで動いているかを先に確かめると、導入後に止まる原因を減らせます。

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

関連する記事

Claude Code をもっと見る →