Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp — это сервер Model Context Protocol (MCP), который подключает агентов кодирования, таких как Claude и Cursor, к вашему запущенному dev-серверу Next.js.

Это тонкий коннектор. Он обнаруживает запущенные dev-серверы Next.js 16+ и проксирует их встроенную MCP-конечную точку (/_next/mcp), чтобы агенты получали живые ошибки времени выполнения, маршруты и логи. Он также включает два шлюза, которые направляют агентов к инструментам, запускаемым ими напрямую: документация, соответствующая версии, и CLI agent-browser.

[!NOTE] Документация и рабочие процессы миграции больше не находятся в этом сервере. Next.js включает собственную документацию в node_modules/next/dist/docs/, а рабочие процессы обновления / Cache Components распространяются как навыки агентов. См. Миграция с 0.3.x.

Требования

• Node.js v20.19 или более новая версия LTS
• npm или pnpm
• Next.js 16+ с запущенным dev-сервером (для nextjs_index / nextjs_call)

Установка

Установите для всех ваших агентов кодирования с помощью add-mcp:

npx add-mcp next-devtools-mcp@latest

Добавьте -y, чтобы пропустить запрос и установить во все обнаруженные агенты. Добавьте -g, чтобы установить глобально во всех проектах.

Или добавьте конфигурацию в ваш MCP-клиент вручную:

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

[!NOTE] next-devtools-mcp@latest поддерживает ваш клиент на последней версии.

Настройка для конкретного клиента

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

Быстрый старт

Запустите ваш dev-сервер Next.js:

npm run dev

Next.js 16+ включает свою MCP-конечную точку по умолчанию в http://localhost:3000/_next/mcp. next-devtools-mcp обнаруживает и подключается к ней автоматически — настройка не требуется.

Затем спросите вашего агента о запущенном приложении:

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?

Агент вызывает nextjs_index для обнаружения серверов, затем nextjs_call для запроса их реального состояния.

Инструменты

Шлюзы не выполняют работу сами — они сообщают агенту, где находится документация или как установить/запустить CLI, и агент запускает его напрямую (быстрее, чем проксирование через MCP).

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

Миграция с 0.3.x

Начиная с 0.4.0, next-devtools-mcp — это тонкий коннектор.

Изменено:

• nextjs_docs больше не загружает документацию по сети. Он направляет агента к документации, которую Next.js включает в node_modules/next/dist/docs/ (или рекомендует обновление). Ресурс nextjs-docs://llms-index удален.

Удалено:

• Инструмент init — он только обеспечивал старый рабочий процесс загрузки документации.
• Инструменты upgrade_nextjs_16 и enable_cache_components и их подсказки — теперь распространяются как навыки агентов.
• Все ресурсы cache-components://, nextjs16:// и nextjs-fundamentals:// — заменены встроенной документацией.

Что осталось: nextjs_index, nextjs_call, nextjs_docs и browser_eval.

Конфиденциальность и телеметрия

next-devtools-mcp собирает анонимную телеметрию использования для улучшения инструмента:

• Использование инструментов — какие MCP-инструменты вызываются (например, nextjs_index, nextjs_call)
• События ошибок — анонимные сообщения об ошибках при сбоях инструментов
• Метаданные сеанса — ID сеанса, временные метки, базовое окружение (ОС, версия Node.js)

Не собирается: ваш код, содержимое или пути файлов, личные данные, учетные данные или аргументы инструментов (только имена инструментов).

Локальные файлы находятся в ~/.next-devtools-mcp/ (анонимный telemetry-id, telemetry-salt и журнал отладки mcp.log).

Отказ от участия — установите переменную окружения (добавьте её в ~/.zshrc / ~/.bashrc для сохранения):

export NEXT_TELEMETRY_DISABLED=1

Удалите локальные данные телеметрии в любое время:

rm -rf ~/.next-devtools-mcp

Устранение неполадок

ERR_MODULE_NOT_FOUND, ссылающийся на next-devtools-mcp/dist — очистите кэш npx и перезапустите ваш MCP-клиент. Сервер переустановится заново.

[error] No server info found — nextjs_index / nextjs_call требуют запущенного dev-сервера Next.js 16+:

1. Запустите его: npm run dev
2. Подтвердите Next.js 16+ (конечная точка /_next/mcp существует только там)
3. Убедитесь, что он запустился без ошибок

browser_eval и nextjs_docs работают без dev-сервера.

Локальная разработка

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

Укажите вашему MCP-клиенту на локальную сборку:

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

Или с Codex:

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

См. документацию MCP для Next.js о том, как MCP работает с Next.js и агентами кодирования.

Лицензия

MIT