Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp é um servidor Model Context Protocol (MCP) que conecta agentes de codificação como Claude e Cursor ao seu servidor de desenvolvimento Next.js em execução.

É um conector leve. Ele descobre servidores de desenvolvimento Next.js 16+ em execução e faz proxy do endpoint MCP integrado (/_next/mcp) para que os agentes recebam erros de runtime, rotas e logs em tempo real. Ele também inclui dois gateways que apontam os agentes para ferramentas que eles executam diretamente: documentação precisa por versão e a CLI agent-browser.

[!NOTE] Documentação e fluxos de migração não vivem mais neste servidor. O Next.js inclui sua própria documentação em node_modules/next/dist/docs/, e os fluxos de upgrade / Cache Components são distribuídos como habilidades de agente. Veja Migrando da 0.3.x.

Requisitos

• Node.js v20.19 ou uma versão LTS mais recente
• npm ou pnpm
• Next.js 16+ com um servidor de desenvolvimento em execução (para nextjs_index / nextjs_call)

Instalação

Instale para todos os seus agentes de codificação com add-mcp:

npx add-mcp next-devtools-mcp@latest

Adicione -y para pular o prompt e instalar em todos os agentes detectados. Adicione -g para instalar globalmente em todos os projetos.

Ou adicione a configuração manualmente ao seu cliente MCP:

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

[!NOTE] next-devtools-mcp@latest mantém seu cliente na versão mais recente.

Configuração 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"]}'

Início Rápido

Inicie seu servidor de desenvolvimento Next.js:

npm run dev

O Next.js 16+ habilita seu endpoint MCP por padrão em http://localhost:3000/_next/mcp. next-devtools-mcp descobre e conecta-se a ele automaticamente — sem necessidade de configuração.

Depois pergunte ao seu agente sobre o aplicativo em execução:

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?

O agente chama nextjs_index para descobrir servidores e depois nextjs_call para consultar o estado real deles.

Ferramentas

Os gateways não fazem o trabalho por conta própria — eles informam ao agente onde está a documentação ou como instalar/executar a CLI, e o agente executa diretamente (mais rápido do que fazer proxy via MCP).

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

Migrando da 0.3.x

A partir da 0.4.0, next-devtools-mcp é um conector leve.

Alterado:

• nextjs_docs não busca mais documentação pela rede. Ela aponta o agente para a documentação que o Next.js inclui em node_modules/next/dist/docs/ (ou recomenda atualizar). O recurso nextjs-docs://llms-index foi removido.

Removido:

• Ferramenta init — ela apenas impunha o fluxo antigo de busca de documentação.
• Ferramentas upgrade_nextjs_16 e enable_cache_components e seus prompts — agora distribuídas como habilidades de agente.
• Todos os recursos cache-components://, nextjs16:// e nextjs-fundamentals:// — substituídos pela documentação incluída.

O que permanece: nextjs_index, nextjs_call, nextjs_docs e browser_eval.

Privacidade e Telemetria

next-devtools-mcp coleta telemetria anônima de uso para melhorar a ferramenta:

• Uso de ferramentas — quais ferramentas MCP são invocadas (ex.: nextjs_index, nextjs_call)
• Eventos de erro — mensagens de erro anônimas quando ferramentas falham
• Metadados de sessão — ID da sessão, timestamps, ambiente básico (SO, versão do Node.js)

Não coletado: seu código, conteúdo ou caminhos de arquivos, dados pessoais, credenciais ou argumentos de ferramentas (apenas nomes de ferramentas).

Arquivos locais ficam em ~/.next-devtools-mcp/ (telemetry-id anônimo, telemetry-salt e um log de depuração mcp.log).

Para desativar, defina a variável de ambiente (adicione-a em ~/.zshrc / ~/.bashrc para persistir):

export NEXT_TELEMETRY_DISABLED=1

Exclua dados de telemetria locais a qualquer momento:

rm -rf ~/.next-devtools-mcp

Solução de Problemas

ERR_MODULE_NOT_FOUND referenciando next-devtools-mcp/dist — limpe o cache do npx e reinicie seu cliente MCP. O servidor reinstala do zero.

[error] No server info found — nextjs_index / nextjs_call precisam de um servidor de desenvolvimento Next.js 16+ em execução:

1. Inicie-o: npm run dev
2. Confirme o Next.js 16+ (o endpoint /_next/mcp só existe nele)
3. Verifique se ele iniciou sem erros

browser_eval e nextjs_docs funcionam sem um servidor de desenvolvimento.

Desenvolvimento Local

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

Aponte seu cliente MCP para o build local:

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

Ou com Codex:

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

Veja a documentação MCP do Next.js para saber como o MCP funciona com Next.js e agentes de codificação.

Licença

MIT