Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp ist ein Model Context Protocol (MCP)-Server, der Coding-Agenten wie Claude und Cursor mit deinem laufenden Next.js-Dev-Server verbindet.

Es ist ein schlanker Connector. Er erkennt laufende Next.js 16+-Dev-Server und leitet deren integrierten MCP-Endpunkt (/_next/mcp) weiter, sodass Agenten Live-Runtime-Fehler, Routen und Logs erhalten. Außerdem enthält er zwei Gateways, die Agenten auf Tools verweisen, die sie direkt ausführen: versionsgenaue Dokumentation und die agent-browser-CLI.

[!NOTE] Dokumentation und Migrations-Workflows befinden sich nicht mehr in diesem Server. Next.js bündelt seine eigene Dokumentation unter node_modules/next/dist/docs/, und Upgrade-/Cache-Components-Workflows werden als Agent-Skills verteilt. Siehe Migration von 0.3.x.

Voraussetzungen

• Node.js v20.19 oder eine neuere LTS-Version
• npm oder pnpm
• Next.js 16+ mit laufendem Dev-Server (für nextjs_index / nextjs_call)

Installation

Installiere für alle deine Coding-Agenten mit add-mcp:

npx add-mcp next-devtools-mcp@latest

Füge -y hinzu, um die Eingabeaufforderung zu überspringen und in allen erkannten Agenten zu installieren. Füge -g hinzu, um global über alle Projekte hinweg zu installieren.

Oder füge die Konfiguration manuell zu deinem MCP-Client hinzu:

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

[!NOTE] next-devtools-mcp@latest hält deinen Client auf der neuesten Version.

Clientspezifische Einrichtung

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

Schnellstart

Starte deinen Next.js-Dev-Server:

npm run dev

Next.js 16+ aktiviert seinen MCP-Endpunkt standardmäßig unter http://localhost:3000/_next/mcp. next-devtools-mcp erkennt und verbindet sich automatisch damit – keine Konfiguration erforderlich.

Frage dann deinen Agenten nach der laufenden App:

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?

Der Agent ruft nextjs_index auf, um Server zu erkennen, und dann nextjs_call, um deren echten Zustand abzufragen.

Tools

Die Gateways erledigen die Arbeit nicht selbst – sie sagen dem Agenten, wo die Dokumentation zu finden ist oder wie die CLI installiert/ausgeführt wird, und der Agent führt sie direkt aus (schneller als über MCP zu proxen).

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

Migration von 0.3.x

Ab 0.4.0 ist next-devtools-mcp ein schlanker Connector.

Geändert:

• nextjs_docs ruft keine Dokumentation mehr über das Netzwerk ab. Es verweist den Agenten auf die Dokumentation, die Next.js unter node_modules/next/dist/docs/ bündelt (oder empfiehlt ein Upgrade). Die nextjs-docs://llms-index-Ressource wurde entfernt.

Entfernt:

• init-Tool — es erzwingt nur den alten Dokumentationsabruf-Workflow.
• upgrade_nextjs_16- und enable_cache_components-Tools und deren Prompts — jetzt als Agent-Skills verteilt.
• Alle cache-components://-, nextjs16://- und nextjs-fundamentals://-Ressourcen — durch die gebündelte Dokumentation ersetzt.

Was bleibt: nextjs_index, nextjs_call, nextjs_docs und browser_eval.

Datenschutz & Telemetrie

next-devtools-mcp sammelt anonyme Nutzungstelemetrie, um das Tool zu verbessern:

• Tool-Nutzung — welche MCP-Tools aufgerufen werden (z. B. nextjs_index, nextjs_call)
• Fehlerereignisse — anonyme Fehlermeldungen, wenn Tools fehlschlagen
• Sitzungsmetadaten — Sitzungs-ID, Zeitstempel, grundlegende Umgebung (Betriebssystem, Node.js-Version)

Nicht erfasst: dein Code, Dateiinhalte oder -pfade, persönliche Daten, Anmeldeinformationen oder Tool-Argumente (nur Toolnamen).

Lokale Dateien liegen unter ~/.next-devtools-mcp/ (anonyme telemetry-id, telemetry-salt und ein Debug-Log mcp.log).

Deaktivieren durch Setzen der Umgebungsvariable (füge sie zu ~/.zshrc / ~/.bashrc hinzu, um sie dauerhaft zu speichern):

export NEXT_TELEMETRY_DISABLED=1

Lösche lokale Telemetriedaten jederzeit:

rm -rf ~/.next-devtools-mcp

Fehlerbehebung

ERR_MODULE_NOT_FOUND verweist auf next-devtools-mcp/dist — leere deinen npx-Cache und starte deinen MCP-Client neu. Der Server installiert sich frisch.

[error] No server info found — nextjs_index / nextjs_call benötigen einen laufenden Next.js 16+-Dev-Server:

1. Starte ihn: npm run dev
2. Bestätige Next.js 16+ (der /_next/mcp-Endpunkt existiert nur dort)
3. Stelle sicher, dass er ohne Fehler gestartet ist

browser_eval und nextjs_docs funktionieren ohne Dev-Server.

Lokale Entwicklung

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

Verweise deinen MCP-Client auf den lokalen Build:

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

Oder mit Codex:

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

Siehe die Next.js-MCP-Dokumentation für Informationen darüber, wie MCP mit Next.js und Coding-Agenten funktioniert.

Lizenz

MIT