Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp est un serveur Model Context Protocol (MCP) qui connecte des agents de codage comme Claude et Cursor à votre serveur de développement Next.js en cours d'exécution.

C'est un connecteur léger. Il détecte les serveurs de développement Next.js 16+ en cours d'exécution et transmet leur point de terminaison MCP intégré (/_next/mcp) afin que les agents reçoivent en direct les erreurs d'exécution, les routes et les journaux. Il fournit également deux passerelles qui orientent les agents vers des outils qu'ils exécutent directement : une documentation adaptée à la version et l'outil CLI agent-browser.

[!NOTE] La documentation et les flux de migration ne vivent plus dans ce serveur. Next.js regroupe sa propre documentation à node_modules/next/dist/docs/, et les flux de mise à niveau / composants de cache sont distribués sous forme de compétences d'agent. Voir Migration depuis 0.3.x.

Prérequis

• Node.js v20.19 ou une version LTS plus récente
• npm ou pnpm
• Next.js 16+ avec un serveur de développement en cours d'exécution (pour nextjs_index / nextjs_call)

Installation

Installez pour tous vos agents de codage avec add-mcp :

npx add-mcp next-devtools-mcp@latest

Ajoutez -y pour ignorer l'invite et installer sur tous les agents détectés. Ajoutez -g pour installer globalement sur tous les projets.

Ou ajoutez la configuration à votre client MCP manuellement :

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

[!NOTE] next-devtools-mcp@latest maintient votre client à la dernière version.

Configuration spécifique au client

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

Démarrage rapide

Démarrez votre serveur de développement Next.js :

npm run dev

Next.js 16+ active son point de terminaison MCP par défaut à http://localhost:3000/_next/mcp. next-devtools-mcp le détecte et s'y connecte automatiquement — aucune configuration requise.

Ensuite, interrogez votre agent sur l'application en cours d'exécution :

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?

L'agent appelle nextjs_index pour découvrir les serveurs, puis nextjs_call pour interroger leur état réel.

Outils

Les passerelles ne font pas le travail elles-mêmes — elles indiquent à l'agent où se trouve la documentation ou comment installer/exécuter l'outil CLI, et l'agent l'exécute directement (plus rapide qu'un proxy via MCP).

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

Migration depuis 0.3.x

À partir de 0.4.0, next-devtools-mcp est un connecteur léger.

Modifié :

• nextjs_docs ne récupère plus la documentation sur le réseau. Il oriente l'agent vers la documentation que Next.js regroupe à node_modules/next/dist/docs/ (ou recommande une mise à niveau). La ressource nextjs-docs://llms-index est supprimée.

Supprimé :

• Outil init — il ne faisait qu'imposer l'ancien flux de récupération de documentation.
• Outils upgrade_nextjs_16 et enable_cache_components et leurs invites — désormais distribués sous forme de compétences d'agent.
• Toutes les ressources cache-components://, nextjs16:// et nextjs-fundamentals:// — remplacées par la documentation groupée.

Ce qui reste : nextjs_index, nextjs_call, nextjs_docs et browser_eval.

Confidentialité et télémétrie

next-devtools-mcp collecte des données de télémétrie anonymes pour améliorer l'outil :

• Utilisation des outils — quels outils MCP sont invoqués (par exemple nextjs_index, nextjs_call)
• Événements d'erreur — messages d'erreur anonymes lorsque les outils échouent
• Métadonnées de session — ID de session, horodatages, environnement de base (système d'exploitation, version de Node.js)

Non collecté : votre code, contenu ou chemins de fichiers, données personnelles, identifiants ou arguments d'outils (uniquement les noms d'outils).

Les fichiers locaux se trouvent sous ~/.next-devtools-mcp/ (telemetry-id anonyme, telemetry-salt et un journal de débogage mcp.log).

Désactivation en définissant la variable d'environnement (ajoutez-la à ~/.zshrc / ~/.bashrc pour la conserver) :

export NEXT_TELEMETRY_DISABLED=1

Supprimez les données de télémétrie locales à tout moment :

rm -rf ~/.next-devtools-mcp

Dépannage

ERR_MODULE_NOT_FOUND faisant référence à next-devtools-mcp/dist — videz votre cache npx et redémarrez votre client MCP. Le serveur se réinstalle proprement.

[error] No server info found — nextjs_index / nextjs_call nécessitent un serveur de développement Next.js 16+ en cours d'exécution :

1. Démarrez-le : npm run dev
2. Confirmez Next.js 16+ (le point de terminaison /_next/mcp n'existe que là)
3. Vérifiez qu'il a démarré sans erreurs

browser_eval et nextjs_docs fonctionnent sans serveur de développement.

Développement local

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

Pointez votre client MCP vers la build locale :

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

Ou avec Codex :

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

Voir la documentation MCP de Next.js pour savoir comment MCP fonctionne avec Next.js et les agents de codage.

Licence

MIT