Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp, Claude ve Cursor gibi kodlama ajanlarını çalışan Next.js geliştirme sunucunuza bağlayan bir Model Bağlam Protokolü (MCP) sunucusudur.

İnce bir bağlayıcıdır. Çalışan Next.js 16+ geliştirme sunucularını keşfeder ve yerleşik MCP uç noktalarını (/_next/mcp) vekil olarak sunar, böylece ajanlar canlı çalışma zamanı hatalarını, rotaları ve günlükleri alır. Ayrıca, ajanları doğrudan çalıştırdıkları araçlara yönlendiren iki ağ geçidi sunar: sürüme uygun dokümanlar ve agent-browser CLI.

[!NOTE] Dokümanlar ve geçiş iş akışları artık bu sunucuda yer almaz. Next.js kendi dokümanlarını node_modules/next/dist/docs/ adresinde paketler ve yükseltme / Önbellek Bileşenleri iş akışları ajan becerileri olarak dağıtılır. Bkz. 0.3.x'ten Geçiş.

Gereksinimler

• Node.js v20.19 veya daha yeni bir LTS sürümü
• npm veya pnpm
• Çalışan bir geliştirme sunucusuna sahip Next.js 16+ (nextjs_index / nextjs_call için)

Kurulum

add-mcp ile tüm kodlama ajanlarınız için kurun:

npx add-mcp next-devtools-mcp@latest

İstemi atlamak ve algılanan tüm ajanlara kurmak için -y ekleyin. Tüm projeler genelinde global olarak kurmak için -g ekleyin.

Veya yapılandırmayı MCP istemcinize manuel olarak ekleyin:

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

[!NOTE] next-devtools-mcp@latest, istemcinizi en son sürümde tutar.

İstemciye özel kurulum

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

Hızlı Başlangıç

Next.js geliştirme sunucunuzu başlatın:

npm run dev

Next.js 16+, MCP uç noktasını varsayılan olarak http://localhost:3000/_next/mcp adresinde etkinleştirir. next-devtools-mcp bunu otomatik olarak keşfeder ve bağlanır — yapılandırma gerekmez.

Ardından ajanınıza çalışan uygulama hakkında soru sorun:

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?

Ajan, sunucuları keşfetmek için nextjs_index'ü, ardından gerçek durumlarını sorgulamak için nextjs_call'i çağırır.

Araçlar

Ağ geçitleri işi kendileri yapmaz — ajana dokümanların nerede olduğunu veya CLI'nin nasıl kurulacağını/çalıştırılacağını söyler ve ajan bunu doğrudan çalıştırır (MCP üzerinden vekil sunmaktan daha hızlıdır).

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

0.3.x'ten Geçiş

0.4.0'dan itibaren, next-devtools-mcp ince bir bağlayıcıdır.

Değişen:

• nextjs_docs artık ağ üzerinden doküman getirmez. Ajanı, Next.js'in node_modules/next/dist/docs/ adresinde paketlediği dokümanlara yönlendirir (veya yükseltme önerir). nextjs-docs://llms-index kaynağı kaldırılmıştır.

Kaldırılan:

• init aracı — yalnızca eski doküman getirme iş akışını zorunlu kılardı.
• upgrade_nextjs_16 ve enable_cache_components araçları ve istemleri — artık ajan becerileri olarak dağıtılmaktadır.
• Tüm cache-components://, nextjs16:// ve nextjs-fundamentals:// kaynakları — paketlenmiş dokümanlar ile yer değiştirmiştir.

Geriye kalanlar: nextjs_index, nextjs_call, nextjs_docs ve browser_eval.

Gizlilik ve Telemetri

next-devtools-mcp, aracı geliştirmek için anonim kullanım telemetrisi toplar:

• Araç kullanımı — hangi MCP araçlarının çağrıldığı (örn. nextjs_index, nextjs_call)
• Hata olayları — araçlar başarısız olduğunda anonim hata mesajları
• Oturum meta verileri — oturum kimliği, zaman damgaları, temel ortam (İşletim Sistemi, Node.js sürümü)

Toplanmayanlar: kodunuz, dosya içerikleri veya yolları, kişisel veriler, kimlik bilgileri veya araç argümanları (yalnızca araç adları).

Yerel dosyalar ~/.next-devtools-mcp/ altında bulunur (anonim telemetry-id, telemetry-salt ve bir hata ayıklama günlüğü mcp.log).

Devre dışı bırakmak için ortam değişkenini ayarlayın (kalıcı olması için ~/.zshrc / ~/.bashrc dosyasına ekleyin):

export NEXT_TELEMETRY_DISABLED=1

Yerel telemetri verilerini istediğiniz zaman silin:

rm -rf ~/.next-devtools-mcp

Sorun Giderme

ERR_MODULE_NOT_FOUND, next-devtools-mcp/dist'e referans veriyor — npx önbelleğinizi temizleyin ve MCP istemcinizi yeniden başlatın. Sunucu yeniden temiz olarak kurulur.

[error] No server info found — nextjs_index / nextjs_call, çalışan bir Next.js 16+ geliştirme sunucusuna ihtiyaç duyar:

1. Başlatın: npm run dev
2. Next.js 16+ olduğunu doğrulayın (/_next/mcp uç noktası yalnızca orada bulunur)
3. Hatasız başladığını doğrulayın

browser_eval ve nextjs_docs, geliştirme sunucusu olmadan çalışır.

Yerel Geliştirme

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

MCP istemcinizi yerel derlemeye yönlendirin:

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

Veya Codex ile:

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

MCP'nin Next.js ve kodlama ajanlarıyla nasıl çalıştığı hakkında Next.js MCP dokümantasyonuna bakın.

Lisans

MIT