Next.js DevTools MCP

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

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

Примечание

Документация и миграционные workflows больше не живут на этом сервере. Next.js упаковывает собственную документацию в node_modules/next/dist/docs/, а workflows обновления / Cache Components распространяются как навыки агента. См. раздел Migrating from 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"]
    }
  }
}

Примечание

next-devtools-mcp@latest держит ваш клиент на самой свежей версии.

Специфичные настройки клиента

Amp

amp mcp add next-devtools -- npx next-devtools-mcp@latest

Или следуйте MCP-документации Amp с конфигурацией выше.

Claude Code

claude mcp add next-devtools npx next-devtools-mcp@latest

Или отредактируйте файл настроек MCP с конфигурацией выше.

Codex

codex mcp add next-devtools -- npx next-devtools-mcp@latest

Windows 11: добавьте переменные окружения и увеличьте таймаут запуска в .codex/config.toml:

env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }
startup_timeout_ms = 20_000

Cursor Установить в Cursor

Или перейдите в Cursor Settings → MCP → New MCP Server и используйте указанную конфигурацию.

Gemini

# Project
gemini mcp add next-devtools npx next-devtools-mcp@latest

# Global
gemini mcp add -s user next-devtools npx next-devtools-mcp@latest

Google Antigravity Добавьте в .gemini/antigravity/mcp_config.json:

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

Смотрите Antigravity MCP docs.

VS Code / Copilot

code --add-mcp '{"name":"next-devtools","command":"npx","args":["-y","next-devtools-mcp@latest"]}'

Или следуйте официальному руководству по настройке MCP для VS Code.

Warp Settings | AI | Manage MCP Servers → + Add:

Имя: next-devtools
Команда: npx
Аргументы: -y, next-devtools-mcp@latest

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

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

npm run dev

Next.js 16+ по умолчанию включает MCP endpoint по адресу 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 для запроса их текущего состояния.

Инструменты

Инструмент	Что делает
nextjs_index	Обнаруживает запущенные dev-серверы Next.js 16+ и перечисляет у каждого встроенные инструменты runtime MCP.
nextjs_call	Вызывает инструмент runtime на найденном сервере (ошибки, маршруты, логи, Server Actions).
nextjs_docs	Gateway. Указывает агенту на версионно-актуальную документацию в node_modules/next/dist/docs/.
browser_eval	Gateway. Указывает агенту на CLI agent-browser для автоматизации в браузере.

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

nextjs_index — обнаружение серверов Сканирует общие порты для запущенных dev-серверов Next.js 16+ и перечисляет встроенные инструменты runtime на /_next/mcp. Параметры не требуются.

Runtime-инструменты, доступные через Next.js (зависит от версии):

get_errors — текущие ошибки сборки, выполнения и типов
get_logs — путь к файлу лога девелопмента (консоль браузера + вывод сервера)
get_page_metadata — маршруты, страницы, метаданные компонентов
get_project_metadata — структура проекта, конфигурации, URL dev-сервера
get_server_action_by_id — разрешение ID Server Action до исходного файла

Вывод: JSON со списком обнаруженных серверов (порт, PID, URL) и их инструментов.

nextjs_call — запустить инструмент runtime Вызывает один инструмент runtime на обнаруженном сервере. Сначала запустите nextjs_index, чтобы найти порт и имя инструмента.

Входные данные:

port (required) — порт dev-сервера
toolName (required) — инструмент runtime, который нужно вызвать
args (optional) — объект аргументов, только если инструмент требует их

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

Вывод: JSON с результатом инструмента.

nextjs_docs — найти версионно-актуальную документацию Не загружает документацию. Next.js 16+ включает всю документацию (в формате markdown, соответствующую установленной версии) в node_modules/next/dist/docs/. Этот инструмент возвращает путь к ней и способ чтения документации, чтобы агент использовал версионно-актуальную документацию, а не догадки по обучающим данным. на более старых версиях Next.js рекомендуется npx @next/codemod@latest upgrade latest.

Вход: topic (optional), project_path (optional, по умолчанию cwd).

browser_eval — настройка автоматизации в браузере Не управляет браузером напрямую. Он определяет, установлен ли agent-browser и возвращает либо точку входа (agent-browser skills get core --full), либо шаги установки (npm install -g agent-browser, затем agent-browser install), чтобы агент запускал CLI напрямую.

Вход: task (optional) — используется только для настройки рекомендаций.

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

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

Изменено:

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

Удалено:

инструмент init — он только принуждал старый workflow загрузки документации.
инструменты и их подсказки 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)
События ошибок — анонимные сообщения об ошибках, когда инструменты работают некорректно
Метаданные сессии — идентификатор сессии, временные метки, базовая окружение (ОС, версия 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 referencing next-devtools-mcp/dist — очистите кэш npx и перезапустите ваш MCP-клиент. Сервер переустановится заново.

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

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

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

Смотрите документацию Next.js MCP — как MCP работает с Next.js и кодирующими агентами:

https://nextjs.org/docs/app/guides/mcp

Лицензия

MIT