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 pengembangan Next.js Anda yang sedang berjalan.

Ini adalah konektor tipis. Ini menemukan server pengembangan Next.js 16+ yang sedang berjalan dan memproksikan endpoint MCP bawaan mereka (/_next/mcp) sehingga agen mendapatkan kesalahan runtime langsung, rute, dan log. Ini juga mengirimkan dua gateway yang mengarahkan agen ke alat yang mereka jalankan secara langsung: dokumentasi yang akurat 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 / Komponen Cache didistribusikan sebagai keterampilan agen. Lihat Migrasi dari 0.3.x.

Persyaratan

• Node.js v20.19 atau versi LTS yang lebih baru
• npm atau pnpm
• Next.js 16+ dengan server pengembangan yang sedang 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 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 pengembangan 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 menghubungkannya 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 sebenarnya.

Alat

Gateway tidak melakukan pekerjaan itu sendiri — mereka memberi tahu agen di mana dokumentasi berada atau bagaimana cara menginstal/menjalankan CLI, dan agen menjalankannya secara langsung (lebih cepat daripada melalui proxy 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. Ini 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 — hanya memberlakukan alur kerja pengambilan dokumentasi lama.
• Alat upgrade_nextjs_16 dan enable_cache_components serta prompt mereka — sekarang didistribusikan sebagai keterampilan agen.
• Semua sumber daya cache-components://, nextjs16://, dan nextjs-fundamentals:// — digantikan oleh dokumentasi yang digabungkan.

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 (mis. nextjs_index, nextjs_call)
• Kejadian kesalahan — pesan kesalahan anonim saat alat gagal
• Metadata sesi — ID sesi, stempel waktu, lingkungan dasar (OS, versi Node.js)

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

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

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

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 yang baru.

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

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

browser_eval dan nextjs_docs berfungsi tanpa server pengembangan.

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 Next.js MCP untuk bagaimana MCP bekerja dengan Next.js dan agen pengkodean.

Lisensi

MIT