next-devtools-mcp

Next.js DevTools MCP

next-devtools-mcp は、Claude や Cursor などのコーディングエージェントを、実行中の Next.js 開発サーバーに接続する Model Context Protocol（MCP）サーバーです。

これは薄いコネクターです。実行中の Next.js 16 以降の開発サーバーを検出し、組み込みの MCP エンドポイント（/_next/mcp）にリクエストをプロキシして、エージェントが実行時エラー、ルート、ログをリアルタイムに取得できるようにします。また、エージェントをエージェント自身が直接実行するツールに接続する、2 つのゲートウェイも提供します。バージョンに正確に対応したドキュメントと、agent-browser CLI です。

メモ

ドキュメントと移行ワークフローは、現在このサーバーには含まれていません。Next.js は独自のドキュメントを node_modules/next/dist/docs/ に同梱しており、アップグレード／Cache Components ワークフローはエージェントスキルとして配布されています。0.3.x からの移行をご覧ください。

要件

• Node.js v20.19 またはそれより新しい LTS バージョン
• npm または pnpm
• Next.js 16 以降と、実行中の開発サーバー（nextjs_index／nextjs_call 用）

インストール

add-mcp を使って、すべてのコーディングエージェントにインストールできます。

npx add-mcp next-devtools-mcp@latest

プロンプトを省略して、検出されたすべてのエージェントにインストールするには -y を追加します。すべてのプロジェクトでグローバルにインストールするには -g を追加します。

または、MCP クライアントに設定を手動で追加します。

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

メモ

next-devtools-mcp@latest を指定すると、クライアントは常に最新バージョンを使用します。

クライアントごとのセットアップ

amp mcp add next-devtools -- npx next-devtools-mcp@latest

claude mcp add next-devtools npx next-devtools-mcp@latest

codex mcp add next-devtools -- npx next-devtools-mcp@latest

env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

# Project
gemini mcp add next-devtools npx next-devtools-mcp@latest

# Global
gemini mcp add -s user next-devtools npx next-devtools-mcp@latest

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

code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'

クイックスタート

Next.js 開発サーバーを起動します。

npm run dev

Next.js 16 以降では、MCP エンドポイントが http://localhost:3000/_next/mcp でデフォルトで有効になります。next-devtools-mcp は自動的に検出して接続するため、設定は不要です。

次に、実行中のアプリについてエージェントに質問します。

Next Devtools, what errors are in my Next.js application?
Next Devtools, show me the structure of my routes
Next Devtools, what's in the development server logs?

エージェントは nextjs_index を呼び出してサーバーを検出し、続いて nextjs_call を呼び出して実際の状態を照会します。

ツール

ゲートウェイ自体は処理を実行しません。ドキュメントの場所や CLI のインストール・実行方法をエージェントに伝え、エージェントが直接実行します（MCP 経由でプロキシするより高速です）。

{ "port": 3000, "toolName": "get_errors" }

0.4.0 以降、next-devtools-mcp は薄いコネクターです。

変更点：

• nextjs_docs はネットワーク経由でドキュメントを取得しなくなりました。エージェントに、Next.js が node_modules/next/dist/docs/ にバンドルしているドキュメントを参照するよう案内します（またはアップグレードを推奨します）。nextjs-docs://llms-index リソースは削除されました。

削除されたもの：

• init ツール — 旧来のドキュメント取得ワークフローを強制するだけのものでした。
• upgrade_nextjs_16 と enable_cache_components ツールおよびそれらのプロンプト — 現在はエージェントスキルとして配布されています。
• すべての cache-components://、nextjs16://、nextjs-fundamentals:// リソース — バンドルされたドキュメントに置き換えられました。

残っているもの：nextjs_index、nextjs_call、nextjs_docs、browser_eval。

プライバシーとテレメトリー

next-devtools-mcp は、ツールの改善のために匿名の使用状況テレメトリーを収集します。

• ツールの使用状況 — 呼び出された MCP ツール（例：nextjs_index、nextjs_call）
• エラーイベント — ツールの失敗時に匿名のエラーメッセージを収集します
• セッションメタデータ — セッション ID、タイムスタンプ、基本的な環境情報（OS、Node.js のバージョン）

収集しないもの： コード、ファイルの内容やパス、個人データ、認証情報、ツールの引数（ツール名のみ）。

ローカルファイルは ~/.next-devtools-mcp/ に保存されます（匿名の telemetry-id、telemetry-salt、デバッグログ mcp.log）。

オプトアウトするには、環境変数を設定します（永続化するには ~/.zshrc / ~/.bashrc に追加してください）。

export NEXT_TELEMETRY_DISABLED=1

ローカルのテレメトリーデータはいつでも削除できます。

rm -rf ~/.next-devtools-mcp

トラブルシューティング

next-devtools-mcp/dist を参照する ERR_MODULE_NOT_FOUND — npx のキャッシュをクリアして、MCP クライアントを再起動してください。サーバーが新たにインストールされます。

[error] No server info found — nextjs_index / nextjs_call の利用には、Next.js 16 以降の開発サーバーが起動している必要があります。

1. 起動します：npm run dev
2. Next.js 16 以降であることを確認します（/_next/mcp エンドポイントはそのバージョン以降にのみ存在します）
3. エラーなしで起動したことを確認します

browser_eval と nextjs_docs は開発サーバーがなくても動作します。

ローカル開発

git clone https://github.com/vercel/next-devtools-mcp.git
cd next-devtools-mcp
pnpm install
pnpm build

MCP クライアントの接続先をローカルビルドに設定します。

{
  "mcpServers": {
    "next-devtools": {
      "command": "node",
      "args": ["/absolute/path/to/next-devtools-mcp/dist/index.js"]
    }
  }
}

または Codex を使用します。

codex mcp add next-devtools-local -- node dist/index.js

MCP が Next.js およびコーディングエージェントとどのように連携するかについては、Next.js MCP ドキュメントをご覧ください。

ライセンス

MIT