Next.js DevTools MCP

Next.js DevTools MCP

next-devtools-mcp는 Claude나 Cursor와 같은 코딩 에이전트를 실행 중인 Next.js 개발 서버에 연결하는 모델 컨텍스트 프로토콜(MCP) 서버입니다.

이것은 경량 커넥터입니다. 실행 중인 Next.js 16+ 개발 서버를 발견하고 내장된 MCP 엔드포인트(/_next/mcp)를 프록시하여 에이전트가 실시간 런타임 오류, 라우트, 로그를 얻을 수 있도록 합니다. 또한 에이전트가 직접 실행하는 도구를 가리키는 두 개의 게이트웨이를 제공합니다: 버전에 정확한 문서와 agent-browser CLI입니다.

[!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+는 기본적으로 http://localhost:3000/_next/mcp에서 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, 타임스탬프, 기본 환경(OS, 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

MCP가 Next.js 및 코딩 에이전트와 작동하는 방식에 대한 자세한 내용은 Next.js MCP 문서를 참조하세요.

라이선스

MIT