Next.js DevTools MCP

Next.js DevTools MCP

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

Es un conector ligero. Descubre servidores de desarrollo Next.js 16+ en ejecución y actúa como proxy de su endpoint MCP integrado (/_next/mcp) para que los agentes obtengan errores de ejecución en vivo, rutas y registros. También incluye dos puertas de enlace que dirigen 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 residen en este servidor. Next.js incluye su propia documentación en node_modules/next/dist/docs/, y los flujos de trabajo de actualización y Componentes de Caché se distribuyen como habilidades del 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

Añade -y para omitir la solicitud e instalar en todos los agentes detectados. Añade -g para instalar globalmente en todos los proyectos.

O añade la configuración a tu cliente MCP manualmente:

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

[!NOTE] next-devtools-mcp@latest mantiene tu cliente en la última versión.

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 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 pregunta 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, luego a nextjs_call para consultar su estado real.

Herramientas

Las puertas de enlace no hacen el trabajo por sí mismas — le dicen 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 a través de un proxy 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.

Cambiado:

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

Eliminado:

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

Lo que permanece: 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 (ej. nextjs_index, nextjs_call)
• Eventos de error — mensajes de error anónimos cuando las herramientas fallan
• 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, contenidos o rutas de archivos, datos personales, credenciales o argumentos de herramientas (solo nombres de herramientas).

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

Para desactivar, establece la variable de entorno (añádela a ~/.zshrc / ~/.bashrc para que persista):

export NEXT_TELEMETRY_DISABLED=1

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

rm -rf ~/.next-devtools-mcp

Solución de Problemas

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

[error] No server info found — nextjs_index / nextjs_call necesitan un servidor de desarrollo 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 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 MCP de Next.js para saber cómo funciona MCP con Next.js y los agentes de codificación.

Licencia

MIT