Next.js DevTools MCP

Next.js DevTools MCP

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

Это тонкий коннектор. Он обнаруживает запущенные серверы разработки 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+ с запущенным сервером разработки (для 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"]}'

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

Запустите ваш сервер разработки 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)
• События ошибок — анонимные сообщения об ошибках при сбоях инструментов
• Метаданные сессии — идентификатор сессии, временные метки, базовая среда (ОС, версия 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 требуется запущенный сервер разработки Next.js 16+:

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

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

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

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 и агентами кодирования.

Лицензия

MIT