App RouterガイドNext.js MCP サーバー

コーディングエージェント向け Next.js MCP サーバーの有効化

モデルコンテキストプロトコル (MCP) は、AIエージェントやコーディングアシスタントが標準化されたインターフェースを通じてアプリケーションと対話できるようにするオープンスタンダードです。Model Context Protocol (MCP)

Next.js は 2 つの MCP サーバーを提供しており、最良のエージェント体験のために両方の使用をお勧めします。

1. Next.js MCP サーバー (組み込み)

Next.js 16 以降で利用可能

Next.js MCP サーバーは、アプリケーションの内部構造を公開し、エージェントが以下を行うことを可能にします。

リアルタイムのアプリケーション状態と実行時情報を取得する
ページメタデータ、ルート、レンダリングの詳細をクエリする
ビルドエラー、実行時エラー、開発ログを取得する
サーバーアクションとコンポーネント階層を検査する

このサーバーは Next.js 開発サーバー内で実行され、アプリケーションの内部状態に直接アクセスできます。

2. Next DevTools MCP (外部パッケージ)

next-devtools-mcp は、高レベルの開発ツールとガイダンスを提供する個別のパッケージです。

Next.js ナレッジベース: 包括的な Next.js ドキュメントとベストプラクティスをクエリする
移行とアップグレードツール: codemods を使用した Next.js 16 へのアップグレードのための自動ヘルパー
キャッシュコンポーネントガイド: キャッシュコンポーネントの設定と構成支援
ブラウザテスト: Playwright MCP を使用したブラウザでのページ検証

さらに、next-devtools-mcp は実行中の Next.js 開発サーバーを自動的に検出し、直接通信して MCP ツール (get_errors、get_logs、get_page_metadata など) にアクセスできます。

これら 2 つの MCP サーバーを組み合わせることで、エージェントは低レベルのアプリケーション内部構造と高レベルの開発ガイダンスの両方を利用できるようになります。

はじめに

組み込みの Next.js MCP サーバーは、Next.js 16 以降の開発環境でデフォルトで有効になっています。

Next DevTools MCP の設定

Next DevTools MCP を使用するには、プロジェクトのルートにある .mcp.json ファイルに next-devtools-mcp を追加します。

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

その他の devtools 機能と設定オプションについては、next-devtools-mcp リポジトリを参照してください。

エージェントとの連携

MCP 互換のコーディングエージェントは、Next.js 開発サーバーを自動的に検出し、接続できます。これにより、エージェントはプロジェクトに関する豊富なコンテキストを利用できます。

エージェント支援開発のメリット

エージェントができること

コンテキストを意識した提案を行う: 既存の構造に基づいて、新しい機能を追加するのに最適な場所を推奨する
ライブアプリケーションの状態をクエリする: 開発中に現在の構成、ルート、ミドルウェアを確認する
アプリルーターのページレイアウトを理解する: ページでレンダリングされているページとレイアウトを正確に把握する
正確な実装を提供する: プロジェクトのパターンと規約に従ったコードを生成する

開発ワークフロー

Next.js 開発サーバーを起動する

npm run dev

コーディングエージェントを実行中の Next.js インスタンスに接続する
ブラウザでアプリケーションを開き、ページを表示する。
エージェントに洞察や診断情報をクエリする (以下の例を参照)

利用可能な Next.js MCP ツール

実験的な Next.js MCP サーバーは、以下のツールを提供します。

get_errors: 開発サーバーから現在のビルドエラー、実行時エラー、型エラーを取得する
get_logs: 開発サーバーのログとコンソール出力を取得する
get_page_metadata: ルート、コンポーネント、レンダリング情報を含む特定のページのメタデータを取得する
get_project_metadata: プロジェクト構造、構成、および全体的なメタデータを取得する
get_server_action_by_id: デバッグと検査のために ID でサーバーアクションを検索する

例

エラー検出と診断

エージェントは、実行中の Next.js アプリケーションからリアルタイムのエラー情報をクエリできます。

User: "What errors are currently in my application?"

エージェントのアクション

Next.js MCP サーバーが提供する get_errors ツールを呼び出す
開発サーバーから現在のビルドエラー、実行時エラー、型エラーを取得する
エラーを分析し、実行可能な修正を提供する

エージェントの応答 (クリックして展開)

> fix errors on the page
 
⏺ I'll help you fix the errors on the page. Let me first check what errors exist by looking at the
  current state of the project.
 
⏺ next-devtools - nextjs_runtime (MCP)(action: "discover_servers")
⏺ next-devtools - nextjs_runtime (MCP)(action: "call_tool", toolName: "get_errors")
 
⏺ I found a hydration error on the /about page. The error shows that the server is rendering
  "server" but the client is rendering "client", causing a mismatch. Let me create a todo list and fix
   this issue.
 
⏺ Perfect! Now let me check for errors on the page.           01:14 PM  claude-sonnet-4-5-20250929
 
⏺ next-devtools - nextjs_runtime (MCP)(action: "call_tool", toolName: "get_errors")
  ⎿ {
      "success": true,
      "port": 3000,
      "toolName": "get_errors",
      "result": {
        "content": [
          {
            "type": "text",
            "text": "# Found errors in 1 browser session(s)\n\n## Session: /about\n\n**1 error(s)
     found**\n\n### Runtime Errors\n\n#### Error 1 (Type: recoverable)\n\n**Error**: Hydration failed

これは、両方の MCP サーバーが有効になっていることの利点を示しています。Next.js MCP サーバーはアプリケーションから直接リアルタイムの診断情報を提供し、next-devtools-mcp はベストプラクティスや移行パスに関するガイダンスを提供できます。

アップグレードとベストプラクティス

Next.js の概念や移行に関するヘルプを求めることもできます。

User: "Help me upgrade my Next.js app to version 16"

エージェントは、next-devtools-mcp を使用して現在のバージョンを分析し、自動移行を codemods でガイドし、非同期 Request API、動的ルートセグメント、ルートハンドラーの戻り値の型などの破壊的変更を処理するためのステップバイステップの説明を提供します。

概念的な質問をすることもできます。

User: "When should I use 'use client' in App Router?"

エージェントは、next-devtools-mcp を介して Next.js ナレッジベースをクエリし、コードベースからの例とともにドキュメントに基づいた説明を提供します。

トラブルシューティング

MCP サーバーが接続できない

Next.js v16 以降を使用していることを確認してください。
開発サーバーを起動します: npm run dev
開発サーバーを再起動します。
MCP クライアントが正しいパスで構成されていることを確認してください。
エージェントの設定に MCP サーバーを追加します。