Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp, Model Context Protocol (MCP) sunucusudur ve Claude ile Cursor gibi kodlama ajanlarını çalışan Next.js dev sunucunuza bağlar.

Bu, ince bir bağlayıcıdır. Çalışan Next.js 16+ dev sunucularını keşfeder ve yerleşik MCP uç noktalarını (/_next/mcp) proxy'ler, 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 içerir: sürüm doğru dokümantasyon ve agent-browser CLI.

[!NOTE] Dokümantasyon ve geçiş iş akışları artık bu sunucuda bulunmuyor. Next.js, kendi dokümantasyonunu node_modules/next/dist/docs/ adresinde paketler ve yükseltme / Cache Components iş akışları ajan becerileri olarak dağıtılır. 0.3.x'ten geçiş bölümüne bakın.

Gereksinimler

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

Kurulum

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

npx add-mcp next-devtools-mcp@latest

İstemi atlamak ve tespit edilen tüm ajanlara kurmak için -y ekleyin. Tüm projelerde genel 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 dev 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 onu 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 çağırır, ardından gerçek durumlarını sorgulamak için nextjs_call çağırır.

Araçlar

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

{ "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şenler:

• nextjs_docs artık dokümantasyonu ağ üzerinden getirmez. Ajanı Next.js'in node_modules/next/dist/docs/ adresinde paketlediği dokümantasyona yönlendirir (veya yükseltmeyi önerir). nextjs-docs://llms-index kaynağı kaldırıldı.

Kaldırılanlar:

• init aracı — yalnızca eski dokümantasyon getirme iş akışını zorunlu kılıyordu.
• upgrade_nextjs_16 ve enable_cache_components araçları ve istemleri — artık ajan becerileri olarak dağıtılıyor.
• Tüm cache-components://, nextjs16:// ve nextjs-fundamentals:// kaynakları — paketlenmiş dokümantasyon tarafından değiştirildi.

Kalanlar: nextjs_index, nextjs_call, nextjs_docs ve browser_eval.

Gizlilik ve Telemetri

next-devtools-mcp, aracı iyileş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 (işletim sistemi, Node.js sürümü)

Toplanmayanlar: kodunuz, dosya içerikleri veya yolları, kişisel veriler, kimlik bilgileri veya araç bağımsız değişkenleri (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ı hale getirmek 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'ye atıfta bulunuyor — npx önbelleğinizi temizleyin ve MCP istemcinizi yeniden başlatın. Sunucu yeniden temiz kurulur.

[error] No server info found — nextjs_index / nextjs_call çalışan bir Next.js 16+ dev sunucusu gerektirir:

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 dev 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