테마 전환
결과물을 파일로 만들어 AI 채팅창에 올리는 방식은 간단하지만, 매번 수정할 때마다 파일을 다시 만들고 업로드해야 하는 수동 단계가 남습니다.
Repomix를 MCP(Model Context Protocol) 서버로 띄우면 이 과정이 완전히 자동화됩니다. AI 어시스턴트가 직접 "지금 이 프로젝트를 묶어서 분석해 줘" 혹은 "결과물에서 특정 패턴의 코드를 찾아줘"라고 요청하고 그 결과를 즉시 받아볼 수 있습니다.
MCP 모드로 실행하기
명령어 한 줄이면 Repomix가 MCP 서버로 동작하기 시작합니다.
bash
repomix --mcp이 기능은 현재 실험 단계로, 사용자 피드백을 통해 계속 발전하고 있습니다. MCP 서버가 활성화되면 어시스턴트는 Repomix가 제공하는 도구(Tool)들을 인식하고, 필요할 때 적절한 파라미터를 넣어 호출하게 됩니다.
클라이언트별 등록 설정
대부분의 MCP 클라이언트는 동일한 실행 명령어를 요구합니다. npx -y repomix --mcp를 stdio 서버로 등록하세요.
| 클라이언트 | 등록 방법 |
|---|---|
| Claude Desktop | claude_desktop_config.json에 설정 추가 |
| Cursor | Settings $\rightarrow$ MCP $\rightarrow$ + Add new global MCP server |
| Cline | cline_mcp_settings.json에 mcpServers.repomix 항목 추가 |
| Claude Code | claude mcp add repomix -- npx -y repomix --mcp |
| VS Code (Insiders) | code --add-mcp '{"name":"repomix","command":"npx","args":["-y","repomix","--mcp"]}' |
| Docker | docker run -i --rm ghcr.io/yamadashy/repomix --mcp |
설정 예시 (JSON):
json
{
"mcpServers": {
"repomix": {
"command": "npx",
"args": ["-y", "repomix", "--mcp"]
}
}
}Claude Code 사용자라면 MCP를 직접 등록하는 것보다 공식 플러그인을 설치하는 것이 훨씬 편리합니다. 더 직관적인 자연어 명령과 간편한 설치 과정을 제공하기 때문입니다. (에이전트 연동 편 참조)
에이전트에게 제공되는 다섯 가지 도구
MCP 서버가 되면 AI는 다음 다섯 가지 도구를 사용할 수 있게 됩니다.
| 도구 이름 | 역할 | 주요 특징 |
|---|---|---|
pack_codebase | 로컬 저장소 묶기 | 프로젝트 전체를 분석용 파일 하나로 생성 |
pack_remote_repository | 원격 저장소 묶기 | GitHub 저장소를 가져와 즉시 분석 파일로 변환 |
read_repomix_output | 출력물 부분 읽기 | 생성된 파일의 특정 줄 범위만 읽어 토큰 절약 |
grep_repomix_output | 출력물 내 패턴 검색 | 정규표현식으로 필요한 코드 조각만 빠르게 탐색 |
file_system_* | 기본 파일 시스템 접근 | 샌드박스 모드에서만 활성화. 파일 읽기/목록 보기 |
pack_codebase: 저장소 전체를 한 번에 묶기
pack_codebase는 CLI의 기본 동작과 같습니다. 다만 파라미터를 통해 세밀하게 조절합니다.
| 파라미터 | 필수 | 기본값 | 설명 |
|---|---|---|---|
directory | 예 | — | 합칠 대상 디렉터리 경로 |
compress | 아니오 | false | Tree-sitter 압축 적용 여부 (토큰 약 70% 절감) |
includePatterns | 아니오 | — | 포함할 파일 glob 패턴 (쉼표 구분) |
ignorePatterns | 아니오 | — | 추가로 제외할 파일 패턴 |
outputPatterns | 아니오 | — | 파일별 포함 수준(전체/압축/구조만) 지정 배열 |
style | 아니오 | xml | 출력 포맷 (xml, markdown, json, plain) |
전략적 팁: outputPatterns를 활용해 "핵심 로직은 원문으로, 주변부는 압축으로" 구성하면 AI가 전체 맥락을 놓치지 않으면서도 효율적으로 분석할 수 있습니다.
read와 grep으로 증분 탐색하기
MCP 워크플로의 진가는 "한 번에 다 읽지 않는 것"에 있습니다.
AI는 먼저 pack_codebase로 전체 구조와 요약을 파악한 뒤, 정말 필요한 부분만 grep과 read로 찾아 읽습니다.
- 탐색 (
grep_repomix_output): 정규표현식으로 특정 함수나 키워드가 포함된 위치를 찾습니다. 앞뒤 컨텍스트 줄(beforeLines,afterLines)을 함께 가져와 주변 맥락을 파악합니다. - 상세 읽기 (
read_repomix_output): 찾은 위치의 정확한 줄 범위(startLine$\rightarrow$endLine)를 지정해 내용을 읽습니다.
이런 증분 탐색(Incremental Exploration) 방식을 쓰면, 수만 줄의 코드가 담긴 대형 프로젝트라도 컨텍스트 창을 거의 소모하지 않고 필요한 정보만 족집게처럼 뽑아낼 수 있습니다. 그래서 MCP 모드에서는 굳이 compress로 내용을 지우지 않고, grep으로 필요한 조각만 가져오는 방식을 권장합니다.
샌드박스 모드: AI의 활동 범위 제한하기
기본 MCP 서버는 호스트 사용자의 권한으로 파일 시스템에 접근할 수 있습니다. 신뢰할 수 없는 에이전트가 시스템 파일에 접근하는 것을 막으려면 --sandbox 옵션을 사용하세요.
bash
repomix --mcp --sandbox path/to/project샌드박스가 활성화되면 다음과 같은 제한이 적용됩니다:
- 경로 제한: 모든 경로 접근은 지정된 루트 디렉터리 기준으로 제한됩니다. 절대 경로,
..,~등을 이용한 루트 밖 탈출(Path Traversal) 시도가 모두 거부됩니다. - 도구 제한: 파일 시스템에 직접 쓰는 동작이나 원격 저장소 설정 로드 등 위험할 수 있는 도구가 비활성화됩니다. 오직 읽기 전용 도구(
pack,read,grep,file_system_read_*)만 등록됩니다. - 설정 무시: 샌드박스 모드에서는 로컬/전역 설정 파일을 로드하지 않습니다. 오직 서버 실행 시 전달된 파라미터만 사용합니다.
이렇게 하면 AI가 프로젝트 폴더라는 "가상 울타리" 안에서만 활동하게 되어, 시스템 보안을 유지하면서도 안전하게 분석을 맡길 수 있습니다.
MCP vs 파일 생성, 어떤 방식이 좋을까
| 기준 | CLI 파일 생성 | MCP 서버 연동 |
|---|---|---|
| 작업 방식 | 수동 생성 $\rightarrow$ 복사 $\rightarrow$ 업로드 | AI가 필요할 때 직접 호출 및 읽기 |
| 데이터 흐름 | 스냅샷 기반 (정적) | 실시간 요청 기반 (동적) |
| 토큰 효율 | 파일 전체를 올리므로 소모량이 큼 | 필요한 조각만 grep으로 읽어 매우 효율적 |
| 보안성 | 사용자가 최종 파일을 검토 후 전달 가능 | AI에게 파일 시스템 접근 권한을 부여해야 함 |
| 추천 상황 | 한 번의 분석으로 끝내거나 타인과 공유할 때 | 장기적인 개발 세션, 실시간 코드 수정 및 분석 시 |
결국 "검토 후 전달"하느냐, "권한을 주고 자동화"하느냐의 차이입니다. 보안이 극도로 중요한 환경이라면 CLI 방식을, 생산성을 극대화하고 싶다면 샌드박스를 적용한 MCP 방식을 추천합니다.
다음 편에서는 플러그인과 에이전트 스킬을 통해 Repomix를 팀의 인프라로 고정시키는 방법을 알아보겠습니다.