Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp adalah server Model Context Protocol (MCP) yang menghubungkan agen pengkodean seperti Claude dan Cursor ke server dev Next.js Anda yang sedang berjalan.

Ini adalah konektor tipis. Ia menemukan server dev Next.js 16+ yang sedang berjalan dan memproksikan endpoint MCP bawaan mereka (/_next/mcp) sehingga agen mendapatkan error runtime, rute, dan log secara langsung. Ia juga menyertakan dua gateway yang mengarahkan agen ke alat yang mereka jalankan secara langsung: dokumentasi yang akurat sesuai versi dan CLI agent-browser.

[!NOTE] Dokumentasi dan alur kerja migrasi tidak lagi berada di server ini. Next.js menggabungkan dokumentasinya sendiri di node_modules/next/dist/docs/, dan alur kerja upgrade / Cache Components didistribusikan sebagai keterampilan agen. Lihat Migrating from 0.3.x.

Persyaratan

• Node.js v20.19 atau versi LTS yang lebih baru
• npm atau pnpm
• Next.js 16+ dengan server dev yang berjalan (untuk nextjs_index / nextjs_call)

Instalasi

Instal untuk semua agen pengkodean Anda dengan add-mcp:

npx add-mcp next-devtools-mcp@latest

Tambahkan -y untuk melewati prompt dan menginstal ke semua agen yang terdeteksi. Tambahkan -g untuk menginstal secara global di semua proyek.

Atau tambahkan konfigurasi ke klien MCP Anda secara manual:

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

[!NOTE] next-devtools-mcp@latest menjaga klien Anda tetap pada versi terbaru.

Pengaturan khusus klien

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"]}'

Mulai Cepat

Mulai server dev Next.js Anda:

npm run dev

Next.js 16+ mengaktifkan endpoint MCP-nya secara default di http://localhost:3000/_next/mcp. next-devtools-mcp menemukan dan terhubung ke sana secara otomatis — tidak perlu konfigurasi.

Kemudian tanyakan agen Anda tentang aplikasi yang sedang berjalan:

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?

Agen memanggil nextjs_index untuk menemukan server, lalu nextjs_call untuk menanyakan status nyata mereka.

Alat

Gateway tidak melakukan pekerjaan itu sendiri — mereka memberi tahu agen di mana dokumentasi berada atau cara menginstal/menjalankan CLI, dan agen menjalankannya secara langsung (lebih cepat daripada memproksikan melalui MCP).

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

Migrasi dari 0.3.x

Mulai dari 0.4.0, next-devtools-mcp adalah konektor tipis.

Berubah:

• nextjs_docs tidak lagi mengambil dokumentasi melalui jaringan. Ia mengarahkan agen ke dokumentasi yang digabungkan Next.js di node_modules/next/dist/docs/ (atau merekomendasikan upgrade). Sumber daya nextjs-docs://llms-index dihapus.

Dihapus:

• Alat init — ia hanya menerapkan alur kerja pengambilan dokumentasi lama.
• Alat upgrade_nextjs_16 dan enable_cache_components beserta prompt mereka — sekarang didistribusikan sebagai keterampilan agen.
• Semua sumber daya cache-components://, nextjs16://, dan nextjs-fundamentals:// — digantikan oleh dokumentasi bawaan.

Yang tersisa: nextjs_index, nextjs_call, nextjs_docs, dan browser_eval.

Privasi & Telemetri

next-devtools-mcp mengumpulkan telemetri penggunaan anonim untuk meningkatkan alat:

• Penggunaan alat — alat MCP mana yang dipanggil (misalnya nextjs_index, nextjs_call)
• Peristiwa error — pesan error anonim saat alat gagal
• Metadata sesi — ID sesi, stempel waktu, lingkungan dasar (OS, versi Node.js)

Tidak dikumpulkan: kode Anda, isi atau jalur file, data pribadi, kredensial, atau argumen alat (hanya nama alat).

File lokal berada di bawah ~/.next-devtools-mcp/ (telemetry-id anonim, telemetry-salt, dan log debug mcp.log).

Menolak dengan mengatur variabel lingkungan (tambahkan ke ~/.zshrc / ~/.bashrc untuk persistensi):

export NEXT_TELEMETRY_DISABLED=1

Hapus data telemetri lokal kapan saja:

rm -rf ~/.next-devtools-mcp

Pemecahan Masalah

ERR_MODULE_NOT_FOUND merujuk next-devtools-mcp/dist — bersihkan cache npx Anda dan mulai ulang klien MCP Anda. Server menginstal ulang dengan bersih.

[error] No server info found — nextjs_index / nextjs_call memerlukan server dev Next.js 16+ yang berjalan:

1. Mulai: npm run dev
2. Konfirmasi Next.js 16+ (endpoint /_next/mcp hanya ada di sana)
3. Verifikasi bahwa ia dimulai tanpa error

browser_eval dan nextjs_docs berfungsi tanpa server dev.

Pengembangan Lokal

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

Arahkan klien MCP Anda ke build lokal:

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

Atau dengan Codex:

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

Lihat dokumentasi MCP Next.js untuk cara MCP bekerja dengan Next.js dan agen pengkodean.

Lisensi

MIT