Next.js MCP Server

Core Idea

Next.js 16+ expõe um endpoint MCP embutido (/_next/mcp) no dev server, permitindo que coding agents acessem em tempo real erros, rotas, Server Actions e metadados da aplicação via o pacote next-devtools-mcp.

Key Concepts

MCP (Model Context Protocol): padrão aberto para agentes de IA interagirem com aplicações via interface padronizada.
next-devtools-mcp: pacote npm que descobre e conecta automaticamente ao dev server Next.js rodando; requer Next.js 16+.
/_next/mcp: endpoint MCP embutido no dev server, base da arquitetura (decoupla interface do agente da implementação interna).
Documentation Gateway: aponta o agente para a documentação versionada em node_modules/next/dist/docs/, garantindo respostas condizentes com a versão instalada.
Compilação sob demanda: compile_route dispara compilação de uma rota específica sem fazer request HTTP (Turbopack only).

Code Examples

// .mcp.json na raiz do projeto
{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

O que demonstra: configuração mínima para habilitar o MCP server; basta rodar next dev depois.

Reference Tables

Tool	Função
`get_errors`	Erros de build, runtime e type atuais do dev server
`get_logs`	Caminho do arquivo de log com console do browser e output do server
`get_page_metadata`	Metadados de páginas específicas (rotas, componentes, rendering)
`get_project_metadata`	Estrutura do projeto, config e URL do dev server
`get_routes`	Todas as rotas (filesystem scan), agrupadas por `appRouter`/`pagesRouter`; segmentos dinâmicos como `[param]`/`[...slug]`
`get_server_action_by_id`	Localiza Server Action por ID (arquivo fonte e nome da função)
`get_compilation_issues`	Warnings/erros de compilação do bundler (Turbopack only)
`compile_route`	Compila rota específica sob demanda via `routeSpecifier` ou `path` (Turbopack only)

Anti-patterns

Usar em Next.js < 16: MCP support não existe antes da v16.
Não reiniciar o dev server após configurar .mcp.json: o servidor precisa estar rodando para next-devtools-mcp descobrir e conectar.

Key Takeaways

Instalar é só adicionar next-devtools-mcp ao .mcp.json e rodar next dev; a conexão é automática.
O agente ganha acesso a erros de hydration, build e runtime em tempo real, sem precisar copiar/colar logs manualmente.
Suporta múltiplas instâncias Next.js em portas diferentes simultaneamente.
Ferramentas de compilação (get_compilation_issues, compile_route) exigem Turbopack.
Também integra Playwright MCP para testes de browser e ajuda em upgrades (npx @next/codemod@latest upgrade latest).

Connects To

Development Environment: outro guia de otimização/diagnóstico do dev server, complementar via Turbopack tracing.
Upgrading guide: usado pelo agente para rodar codemods de upgrade automaticamente.