Next.js DevTools MCP Server

Next.js DevTools MCP

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

Es handelt sich um einen schlanken Konnektor. Er erkennt laufende Next.js 16+-Entwicklungsserver und leitet deren integrierten MCP-Endpunkt (/_next/mcp) weiter, sodass Agenten Live-Laufzeitfehler, Routen und Protokolle erhalten. Außerdem enthält er zwei Gateways, die Agenten auf direkt ausführbare Werkzeuge verweisen: 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- sowie Cache-Components-Workflows werden als Agenten-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 einem laufenden Entwicklungsserver (für nextjs_index / nextjs_call)

Installation

Installieren Sie für alle Ihre Coding-Agenten mit add-mcp:

npx add-mcp next-devtools-mcp@latest

Fügen Sie -y hinzu, um die Eingabeaufforderung zu überspringen und für alle erkannten Agenten zu installieren. Fügen Sie -g hinzu, um projektübergreifend global zu installieren.

Oder fügen Sie die Konfiguration manuell zu Ihrem MCP-Client hinzu:

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

[!NOTE] next-devtools-mcp@latest hält Ihren Client auf dem neuesten Stand.

Client-spezifische 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

Starten Sie Ihren Next.js-Entwicklungsserver:

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 – keine Konfiguration erforderlich.

Fragen Sie dann Ihren Agenten zur 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 tatsächlichen Zustand abzufragen.

Werkzeuge

Die Gateways führen die Arbeit nicht selbst aus – sie teilen dem Agenten mit, wo sich die Dokumentation befindet oder wie die CLI installiert/ausgeführt wird, und der Agent führt sie direkt aus (schneller als die Weiterleitung über MCP).

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

Migration von 0.3.x

Ab Version 0.4.0 ist next-devtools-mcp ein schlanker Konnektor.

Geändert:

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

Entfernt:

• init-Werkzeug — es erzwang nur den alten Workflow zum Abrufen von Dokumentation.
• upgrade_nextjs_16- und enable_cache_components-Werkzeuge und deren Eingabeaufforderungen — jetzt als Agenten-Skills verteilt.
• Alle cache-components://-, nextjs16://- und nextjs-fundamentals://-Ressourcen — ersetzt durch die gebündelte Dokumentation.

Verbleibend: nextjs_index, nextjs_call, nextjs_docs und browser_eval.

Datenschutz & Telemetrie

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

• Werkzeugnutzung — welche MCP-Werkzeuge aufgerufen werden (z. B. nextjs_index, nextjs_call)
• Fehlerereignisse — anonyme Fehlermeldungen bei Werkzeugfehlern
• Sitzungsmetadaten — Sitzungs-ID, Zeitstempel, grundlegende Umgebung (Betriebssystem, Node.js-Version)

Nicht gesammelt: Ihr Code, Dateiinhalte oder -pfade, persönliche Daten, Anmeldeinformationen oder Werkzeugargumente (nur Werkzeugnamen).

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

Opt-out durch Setzen der Umgebungsvariable (zu ~/.zshrc / ~/.bashrc hinzufügen, um sie dauerhaft zu machen):

export NEXT_TELEMETRY_DISABLED=1

Lokale Telemetriedaten jederzeit löschen:

rm -rf ~/.next-devtools-mcp

Fehlerbehebung

ERR_MODULE_NOT_FOUND verweist auf next-devtools-mcp/dist — Leeren Sie Ihren npx-Cache und starten Sie Ihren MCP-Client neu. Der Server wird frisch neu installiert.

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

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

browser_eval und nextjs_docs funktionieren ohne Entwicklungsserver.

Lokale Entwicklung

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

Verweisen Sie Ihren 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 zur Funktionsweise von MCP mit Next.js und Coding-Agenten.

Lizenz

MIT