Next.js DevTools MCP — 사용 사례, 설치 & 라이브 데모

Name: Next.js DevTools MCP Server
Author: vercel

왜 쓰나요

핵심 기능

퍼스트 파티 — Vercel / Next.js 팀이 유지보수
nextjs_docs — 권위 있는 문서 검색, 환각 없음
browser_eval — 앱 테스트를 위한 in-MCP Playwright
nextjs_index / nextjs_call — Next 16 dev 서버 진단과 통신

라이브 데모

실제 사용 모습

vercel.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

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

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

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

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "vercel": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@vercel/next-devtools-mcp"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add vercel -- npx -y @vercel/next-devtools-mcp

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Next.js DevTools

가이드가 있는 codemods를 사용하여 Next.js 프로젝트를 v16으로 업그레이드합니다

👤 v14/v15에서 작업 중인 Next.js 엔지니어 ⏱ ~60 min advanced

언제 쓸까: Next 16 업그레이드를 미루고 있었습니다. 에이전트가 codemods를 실행하고 비동기 API 마이그레이션을 수정하기를 원합니다.

사전 조건

v14+ 버전의 Next.js 프로젝트 — package.json을 확인합니다
클린 git 작업 트리 — git status 결과가 클린 상태입니다. 필요한 경우 되돌릴 수 있습니다

흐름

업그레이드 도구 실행

이 프로젝트에서 upgrade_nextjs_16을 실행합니다. 적용하기 전에 각 codemod를 단계별로 설명합니다.✓ 복사됨

→ 변경 사항의 목록 및 미리 보기 위한 diffs
비동기 API 호출 사이트 수정

codemods 이후 프로젝트를 빌드합니다. cookies()/headers()의 이제 비동기 오류가 발생하면 호출 사이트를 수정하여 await를 사용합니다.✓ 복사됨

→ 빌드 성공
Cache Components 활성화

enable_cache_components를 실행합니다. 보고된 모든 경계 오류를 수정합니다.✓ 복사됨

→ Cache components 활성화됨, 앱 실행 중

결과: 산재된 일 주 대신 하나의 집중된 세션에서 Cache Components가 있는 작동하는 Next 16 프로젝트입니다.

함정

Codemods는 사용자 지정 패턴의 비동기 사용을 수정할 수 없습니다 — 각 codemod 단계 후 빌드를 실행합니다. codemod이 'REVIEW' 주석을 태그할 때 수동으로 수정합니다
타사 라이브러리가 Next 16에 준비되지 않을 수 있습니다 — 업그레이드하기 전에 패키지 호환성을 확인합니다. 손상된 라이브러리를 고정하고 업스트림에 문제를 보고합니다

함께 쓰기: git

진단 엔드포인트를 통해 실행 중인 Next dev 서버를 디버깅합니다

👤 v16+ 버전에서 작업 중인 Next.js 엔지니어 ⏱ ~20 min advanced

언제 쓸까: next dev가 실행 중이지만 뭔가 이상합니다(이상한 hydration, 잘못된 렌더 모드). Next 16+은 /_next/mcp를 통해 런타임 도구를 노출합니다.

사전 조건

Next.js 16+ dev 서버 실행 중 — npm run dev

흐름

서버 검색

nextjs_index를 실행하여 로컬 Next dev 서버를 찾고 노출된 진단 도구를 나열합니다.✓ 복사됨

→ 포트 + 도구 목록
진단 도구 호출

포트 <PORT>에서 nextjs_call을 사용하여 /dashboard의 경로 트리 및 렌더 모드를 가져옵니다. 정적입니까, 동적입니까, 또는 부분입니까?✓ 복사됨

→ 설명이 있는 경로당 렌더 모드
잘못된 렌더 수정

/dashboard 페이지는 cookies()를 사용하여 부분 사전 렌더링을 원했을 때 완전히 동적으로 만듭니다. 문제의 import를 찾고 격리하도록 리팩토링합니다.✓ 복사됨

→ 수정 후 렌더 모드가 부분으로 변경됨

결과: 20개의 블로그 포스트를 읽지 않고도 Next의 렌더링 결정에 대한 통찰력입니다.

함정

Dev 서버 진단은 prod 빌드 출력과 다릅니다 — 항상 next build로 확인합니다. dev 모드는 다른 기본값을 가집니다

Next.js 질문에 대한 권위 있는 답변을 얻습니다

👤 모든 수준의 Next.js 개발자 ⏱ ~10 min beginner

언제 쓸까: Next.js 동작에 대한 질문이 있습니다. LLM 환각을 원하지 않습니다. 인용을 원합니다.

흐름

문서 검색

nextjs_docs를 사용하여 인증을 위한 middleware vs route handlers에 대한 공식 가이드를 찾습니다. 일치하는 섹션을 반환합니다.✓ 복사됨

→ URL이 있는 인용된 문서 섹션
인용과 함께 답변

해당 섹션만을 기반으로, Next 16 앱에서 JWT 유효성 검사에 어떤 것을 사용해야 하며, 그 이유는 무엇입니까? 문서 URL을 포함합니다.✓ 복사됨

→ URL이 있는 근거 있는 답변
내 코드에 적용

middleware.ts에서 현재 구현을 단계별로 설명합니다. 문서의 권장 사항과 일치합니까?✓ 복사됨

→ 구체적인 갭 목록

결과: 분위기가 아닌 문서로 뒷받침되는 권위 있는 Next.js 결정입니다.

함정

문서는 출시 후 몇 주 동안 최신 릴리스보다 뒤떨어집니다 — 최신 기능의 경우 Next.js RFC / 블로그 게시물도 확인합니다

Next.js 앱에서 E2E 확인을 실행합니다

👤 Next.js 엔지니어 ⏱ ~10 min intermediate

언제 쓸까: 방금 변경했습니다. 커밋하기 전에 빠른 smoke 테스트를 원합니다.

흐름

네비게이션 및 캡처

browser_eval을 사용하여 http://localhost:3000/pricing을 엽니다. 스크린샷을 찍고 콘솔 오류를 캡처합니다.✓ 복사됨

→ 스크린샷 + 콘솔 요약
주요 경로를 클릭합니다

'Select Pro plan'을 클릭하고, 정확한 가격으로 체크아웃 모달이 열렸는지 확인합니다. 각 단계를 스크린샷합니다.✓ 복사됨

→ 단계당 통과/실패
보고

요약: 정상 / 손상됨 / 의심스러움. 실패한 경우 콘솔 오류를 붙여 넣습니다.✓ 복사됨

→ 배포 또는 미배포 판정

결과: dev 루프에 포함된 빠른 sanity 확인입니다. 별도의 Playwright 실행기가 필요하지 않습니다.

함정

browser_eval은 Playwright-lite이며 전체 E2E 스위트의 대체가 아닙니다 — 빠른 확인을 위해 사용합니다. 릴리스 게이트를 위해 실제 Playwright 스위트를 유지합니다

함께 쓰기: playwright

조합

다른 MCP와 조합해 10배 효율

vercel + playwright

빠른 확인을 위한 browser_eval, 전체 회귀 스위트를 위한 Playwright

browser_eval을 사용하여 /pricing을 smoke 테스트합니다. 통과하면 주요 흐름에서 Playwright 스위트를 실행합니다.✓ 복사됨

vercel + git

Next 업그레이드, 각 단계에서 커밋

upgrade_nextjs_16을 실행합니다. 각 codemod 후 diff를 설명적 메시지와 함께 커밋하여 뭔가 손상되면 이분 검색할 수 있습니다.✓ 복사됨

vercel + sentry

업그레이드 후 모니터링

Next 16 빌드를 스테이징에 배포합니다. Sentry를 24시간 동안 시청하고 비동기 API 마이그레이션으로 인한 새로운 오류를 플래그합니다.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
init		새 대화에서 첫 호출	free
nextjs_docs	query	모든 Next.js 사실 질문	free
browser_eval	actions (navigate, click, screenshot, etc.)	dev 서버의 빠른 E2E 테스트	free (local browser)
nextjs_index		Next 16+ dev 서버 검색	free
nextjs_call	port, tool_name, args	Next 16+ 런타임 진단 호출	free
upgrade_nextjs_16	project_path	v14/15에서 v16으로의 업그레이드 경로	free
enable_cache_components	project_path	v16 앱에서 Cache Components 켜기	free

비용 및 제한

운영 비용

API 쿼터: 무료 — 로컬 실행 + 문서 검색
호출당 토큰: 문서 반환은 클 수 있습니다. 검색에 제한을 설정하세요
금액: 무료
팁: 에이전트가 사용 가능한 도구를 알 수 있도록 세션당 한 번 init을 실행합니다. 무작위 시행착오를 절약합니다

보안

권한, 시크릿, 파급범위

자격 증명 저장: 없음 — 로컬 도구

데이터 외부 송신: 문서 검색은 vercel.com을 확인하고; browser_eval은 네비게이션하는 곳으로 이동하고; Vercel로의 원격 측정(NEXT_TELEMETRY_DISABLED를 통해 옵트아웃)

문제 해결

자주 발생하는 오류와 해결

nextjs_index가 서버를 찾지 못함

Next.js 16+ dev 서버만 /_next/mcp를 노출합니다. 먼저 업그레이드하거나 이전 버전에는 browser_eval을 사용하세요.

확인: curl http://localhost:3000/_next/mcp

browser_eval이 시작되지 않음

Playwright 바이너리가 누락되었습니다. npx playwright install을 한 번 실행하세요.

Codemod이 파일을 절반 마이그레이션된 상태로 남김

git을 통해 되돌리기, 그런 다음 모두 한 번에가 아니라 한 번에 하나씩 codemods를 실행합니다. 각 사이에 커밋합니다.

nextjs_docs가 관련 없는 결과를 반환함

쿼리에 Next.js 주요 버전을 추가하세요. 단지 'middleware'가 아닌 'app router middleware in Next 16'입니다.

대안

Next.js DevTools 다른 것과 비교

대안	언제 쓰나	단점/장점
Playwright MCP	전체 Playwright가 필요하며, lite browser_eval이 아닙니다	더 강력하지만 Next.js 특정 진단 또는 문서 검색이 없습니다
Cloud Run MCP	Vercel이 아닌 GCP에 배포합니다	다른 호스팅 모델입니다. 이 MCP는 배포 중심이 아닌 Next.js DX 중심입니다

Next.js DevTools

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: Next.js DevTools

가이드가 있는 codemods를 사용하여 Next.js 프로젝트를 v16으로 업그레이드합니다

사전 조건

흐름

함정

진단 엔드포인트를 통해 실행 중인 Next dev 서버를 디버깅합니다

사전 조건

흐름

함정

Next.js 질문에 대한 권위 있는 답변을 얻습니다

흐름

함정

Next.js 앱에서 E2E 확인을 실행합니다

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Next.js DevTools 다른 것과 비교

더 보기

리소스