Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp es un servidor de Model Context Protocol (MCP) que conecta agentes de codificación como Claude y Cursor a tu servidor de desarrollo de Next.js en ejecución.

Es un conector ligero. Descubre servidores de desarrollo de Next.js 16+ en ejecución y hace de proxy a su endpoint MCP integrado (/_next/mcp) para que los agentes obtengan errores de runtime, rutas y registros en vivo. También incluye dos puertas de enlace que apuntan a los agentes hacia herramientas que ejecutan directamente: documentación precisa según la versión y la CLI de agent-browser.

[!NOTE] La documentación y los flujos de migración ya no viven en este servidor. Next.js incluye su propia documentación en node_modules/next/dist/docs/, y los flujos de trabajo de actualización / Cache Components se distribuyen como habilidades de agente. Consulta Migración desde 0.3.x.

Requisitos

• Node.js v20.19 o una versión LTS más reciente
• npm o pnpm
• Next.js 16+ con un servidor de desarrollo en ejecución (para nextjs_index / nextjs_call)

Instalación

Instala para todos tus agentes de codificación con add-mcp:

npx add-mcp next-devtools-mcp@latest

Agrega -y para omitir la confirmación e instalar en todos los agentes detectados. Agrega -g para instalar globalmente en todos los proyectos.

O agrega la configuración manualmente a tu cliente MCP:

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

[!NOTE] next-devtools-mcp@latest mantiene tu cliente en la versión más reciente.

Configuración específica por cliente

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

Inicio rápido

Inicia tu servidor de desarrollo de Next.js:

npm run dev

Next.js 16+ habilita su endpoint MCP por defecto en http://localhost:3000/_next/mcp. next-devtools-mcp lo descubre y se conecta automáticamente — no se necesita configuración.

Luego pregúntale a tu agente sobre la aplicación en ejecución:

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?

El agente llama a nextjs_index para descubrir servidores, y luego a nextjs_call para consultar su estado real.

Herramientas

Las puertas de enlace no hacen el trabajo por sí mismas — le indican al agente dónde está la documentación o cómo instalar/ejecutar la CLI, y el agente la ejecuta directamente (más rápido que hacer proxy a través de MCP).

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

Migración desde 0.3.x

A partir de 0.4.0, next-devtools-mcp es un conector ligero.

Cambios:

• nextjs_docs ya no obtiene documentación a través de la red. Apunta al agente hacia la documentación que Next.js incluye en node_modules/next/dist/docs/ (o recomienda actualizar). El recurso nextjs-docs://llms-index se eliminó.

Eliminado:

• Herramienta init — solo imponía el flujo de trabajo antiguo de obtención de documentación.
• Herramientas upgrade_nextjs_16 y enable_cache_components y sus prompts — ahora se distribuyen como habilidades de agente.
• Todos los recursos cache-components://, nextjs16:// y nextjs-fundamentals:// — reemplazados por la documentación incluida.

Lo que queda: nextjs_index, nextjs_call, nextjs_docs y browser_eval.

Privacidad y telemetría

next-devtools-mcp recopila telemetría de uso anónima para mejorar la herramienta:

• Uso de herramientas — qué herramientas MCP se invocan (p. ej. nextjs_index, nextjs_call)
• Eventos de error — mensajes de error anónimos cuando fallan las herramientas
• Metadatos de sesión — ID de sesión, marcas de tiempo, entorno básico (SO, versión de Node.js)

No se recopila: tu código, contenido o rutas de archivos, datos personales, credenciales o argumentos de herramientas (solo nombres de herramientas).

Los archivos locales viven en ~/.next-devtools-mcp/ (telemetry-id anónimo, telemetry-salt y un registro de depuración mcp.log).

Exclusión voluntaria configurando la variable de entorno (agrégala a ~/.zshrc / ~/.bashrc para persistir):

export NEXT_TELEMETRY_DISABLED=1

Elimina los datos de telemetría locales en cualquier momento:

rm -rf ~/.next-devtools-mcp

Solución de problemas

ERR_MODULE_NOT_FOUND que hace referencia a next-devtools-mcp/dist — limpia tu caché de npx y reinicia tu cliente MCP. El servidor se reinstala desde cero.

[error] No server info found — nextjs_index / nextjs_call necesitan un servidor de desarrollo de Next.js 16+ en ejecución:

1. Inícialo: npm run dev
2. Confirma Next.js 16+ (el endpoint /_next/mcp solo existe allí)
3. Verifica que se inició sin errores

browser_eval y nextjs_docs funcionan sin un servidor de desarrollo.

Desarrollo local

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

Apunta tu cliente MCP a la compilación local:

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

O con Codex:

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

Consulta la documentación de MCP de Next.js para saber cómo funciona MCP con Next.js y los agentes de codificación.

Licencia

MIT