modelcontextprotocol/inspector웹 UI, CLI 또는 TUI에서 Model Context Protocol(MCP) 서버를 검사, 디버그 및 시각적으로 테스트할 수 있으며, 도구/리소스 탐색, 요청 로깅 및 OAuth 지원을 제공합니다.
Model Context Protocol(MCP) 서버를 검사하기 위한 개발자 도구입니다. 단일 패키지인 @modelcontextprotocol/inspector로 제공되며, 서버를 검사하는 세 가지 방법을 제공합니다:
세 가지 모두 단일 전역 mcp-inspector 바이너리로 실행됩니다:
npx @modelcontextprotocol/inspector # 웹 UI (기본값)
npx @modelcontextprotocol/inspector --cli # CLI
npx @modelcontextprotocol/inspector --tui # TUI
v1에서 업그레이드하시나요? v1 → v2 마이그레이션 가이드를 읽어보세요 — CLI 플래그, 새로운
--config대--catalog구분, Node 엔진 버전 상향, 그리고 더 이상 제공되지 않는 항목에 대해 설명합니다.
저장소 상태. 이 저장소는 Inspector의 라인입니다. 활발한 개발은 (개발 브랜치 — 모든 v2 PR이 이 브랜치를 대상으로 함)에서 이루어지며, 마일스톤 릴리스 시점에 ****으로 병합됩니다. 은 기본 브랜치이며 최신 릴리스된 v2를 보유하고 npm 태그로 게시됩니다. 레거시 라인은 ****에 있으며 — 보안 수정만 적용되며, 해당 브랜치에서 npm 태그()로 직접 게시됩니다. 브랜치/보드 규칙은 를 참조하세요.
v2/mainmainmainlatestv1/mainv1-latestnpx @modelcontextprotocol/inspector@v1-latestNode >=22.19.0 필요.
npm install # 저장소 루트에서 실행; postinstall이 모든 클라이언트로 연쇄 실행됨
npm run build # web → cli → tui → launcher
일상적인 웹 반복 작업의 경우 Vite를 직접 실행하세요 — 빠른 HMR, 런처 빌드 불필요:
cd clients/web && npm run dev
런처 기반 스크립트는 빌드된 런처를 실행하므로 먼저 빌드하세요:
npm run web # clients/web/dist에 대한 프로덕션 웹 런처
npm run web:dev # --dev 모드의 웹 런처 (Vite)
v2는 npm 워크스페이스가 아닙니다 — clients/* 아래의 각 클라이언트는 자체 package.json과 node_modules를 유지하며, 공유 코드는 core/에 있으며 @inspector/core 빌드 타임 별칭을 통해 사용됩니다. core/가 가져오는 모든 런타임 의존성은 저장소 루트 package.json에 한 번만 선언되며, 각 클라이언트는 해당 클라이언트만 사용하는 것(UI 스택, 번들러 인라인 패키지, 개발 도구)만 선언하므로 clients/cli와 clients/launcher에는 자체 런타임 의존성이 없습니다. 의존성 추가(루트 대 클라이언트, dependencies 대 devDependencies, 번들러 external 목록)의 의미는 local-dev 스킬에 있습니다.
inspector/
├── clients/
│ ├── web/ 웹 클라이언트 (Vite + React + Mantine). src/ = 브라우저 앱; server/ = Node 백엔드
│ ├── cli/ CLI 클라이언트 (tsup 번들, @inspector/core 별칭)
│ ├── tui/ TUI 클라이언트 (Ink + React, tsup 번들)
│ └── launcher/ 공유 런처 — `mcp-inspector` bin 제공, web/cli/tui로 디스패치
├── core/ `@inspector/core` 별칭을 통해 사용되는 공유 코드 (package.json 없음)
├── test-servers/ 통합 및 스모크 테스트에 사용되는 구성 가능한 MCP 테스트 서버 + 픽스처
├── scripts/ 루트 빌드/검증 도구 (설치 연쇄, 스모크, verify:* 가드)
│ 및 CI에서 실행되는 저장소 자동화 (의존성, Dependabot 알림 및 SDK 스윕)
├── docs/ 작업 중심 가이드 — 아래 참조
├── specification/ 설계/빌드 사양
├── .claude/skills/ 에이전트 스킬: 저장소의 절차, 이름으로 호출 가능
├── AGENTS.md 에이전트와 인간 모두를 위한 기여 규칙
└── README.md 현재 위치
| 가이드 | 내용 |
|---|---|
| 아키텍처 | @inspector/core 공유 패키지와 웹 클라이언트의 "단순 컴포넌트" + Storybook 접근 방식 |
| 테스팅 및 품질 게이트 | 각 validate / coverage / smoke / verify:* 스크립트가 다루는 범위, GitHub-CI-대-로컬-게이트 구분, 지원 브라우저 |
| 스킬 작성 | 실제로 발동되는 스킬 설명 작성 방법과 이를 측정하는 평가 사례 — 작동하는 사례 형태와 튜닝 루프 |
| 테스트 서버 | 구성 가능한 테스트 서버와 모든 기능에 대한 쇼케이스 구성 — 실행할 항목, 클릭할 항목, 그리고 깨진 빌드가 무엇을 했는지 |
| 게시 | 타르볼에 포함되는 항목, 패키징 불변 조건, pack:verify |
| Docker | 컨테이너 이미지 실행 — 포트, 볼륨, 시크릿 위치 |
| v1에서 v2로 마이그레이션 | CLI 플래그 매핑, --config 대 --catalog, Node 엔진 버전 상향, 환경 변수 이름 변경 |
| MCP 서버 구성 | Inspector가 연결하는 서버와 구성 파일 형식 |
| MCP 앱 검토 | 자동화된 앱 도구 검토를 위한 CLI 우선 → 일회성 웹 레시피 |
| MCP 서버 스모크 테스트 | 셸 또는 CI 작업을 위한 연결 → 목록 → 호출 → 검증 워크플로: --format json + jq, 종료 코드 맵, OAuth 비대화형 유지 |
| 런처 및 구성 통합 | 런처가 클라이언트를 별도 프로세스로 실행하지 않고 인프로세스로 실행하는 이유 |
각 클라이언트는 자체 폴더에서 자체 검증을 수행하며, 루트 스크립트가 이를 연결합니다. 집계된 루트 test 스크립트는 없습니다.
npm run validate # 빠른 내부 루프: format:check + lint + typecheck + build + 단위 테스트
npm run coverage # 파일별 ≥90% 게이트 (lines/statements/functions/branches)
npm run local:gate # 푸시 전 필수 — GitHub CI의 엄격한 상위 집합
npm run local:gate는 아래의 모든 검사와 스모크 및 Storybook 테스트를 연결합니다. 테스팅 및 품질 게이트는 단계 목록을 관리하며 각 단계가 다루는 내용과 두 단계가 로컬 전용인 이유를 설명합니다. AGENTS.md에는 테스팅 규칙 자체가 있습니다.
AGENTS.md, CLAUDE.md 및 스킬AGENTS.md는 이 코드베이스를 변경하기 위한 계약이며 인간과 AI 에이전트 모두에게 적용됩니다. 에이전트 전용 보일러플레이트가 아닙니다 — 프로젝트의 실제 규칙(버전/라벨 규칙, TypeScript 및 Mantine/React 표준, 테스팅 및 커버리지 요구 사항, 필수 푸시 전 게이트)을 담고 있습니다. 변경하기 전에 읽고, 구조, 도구 또는 규칙을 변경할 때 최신 상태로 유지하세요.
저장소의 절차(명령과 실제 ID가 포함된 다단계 레시피)는 대신 .claude/skills/에 있으며, 절차별로 하나의 디렉터리로 구성되어 작업이 필요할 때만 로드됩니다. 이는 일반 커밋된 Markdown입니다: 스킬을 이해하지 못하는 에이전트도 읽을 수 있으며, AGENTS.md에는 존재하는 항목의 인덱스가 포함되어 있습니다. Claude Code 사용자는 이름으로 호출합니다(/release, /issue-triage, …).
CLAUDE.md는 Claude Code가 자동으로 로드하는 진입점입니다. AGENTS.md를 포함하므로 에이전트와 인간은 동일한 진실 소스에서 작업합니다. AGENTS.md를 읽는 다른 에이전트를 사용한다면 동일한 규칙을 얻습니다.
여기서 강조할 핵심 규칙: 모든 작업은 이슈 기반입니다. 시작하기 전에 v2 프로젝트 보드에서 추적 이슈를 찾거나 생성하세요. Closes #<issue>와 함께 v2/main에 대해 PR을 여세요. 외부 기여는 풀 리퀘스트가 아닌 이슈로 받습니다 — CONTRIBUTING.md를 참조하세요.
MIT.