MCP: Claude가 로컬 파일과 지능적으로 상호작용하는 방법

Model Context Protocol(MCP)은 애플리케이션이 샌드박스 방식으로 파일 시스템과 상호작용할 수 있도록 하는 안전한 프레임워크를 제공합니다. 이 가이드에서는 MCP가 어떻게 동작하는지, 주요 기능은 무엇인지, 그리고 MCP 파일 시스템 서버를 활용한 실전 예시를 설명합니다.

Model Context Protocol(MCP)이란?

Model Context Protocol(MCP)은 애플리케이션(예: AI 어시스턴트)과 외부 시스템, 특히 파일 시스템 간의 제어된 상호작용을 가능하게 하는 강력한 보안 프레임워크입니다. MCP는 안전한 다리 역할을 하며, 도구들이 샌드박스와 권한 기반 환경에서 파일 읽기, 쓰기, 검색 등의 작업을 수행할 수 있도록 해줍니다.

이 프로토콜은 VS Code, Claude Desktop 또는 기타 개발 환경과 같은 애플리케이션에 파일 시스템 작업을 통합하면서도 강력한 보안 경계를 유지하고자 하는 개발자들에게 특히 유용합니다.

MCP의 주요 특징

• 샌드박스 작업: 모든 활동은 미리 정의된 디렉터리 내에서만 이루어져 파일 시스템의 민감한 영역을 보호합니다.
• 표준화된 API: 통합된 인터페이스를 통해 접근 가능한 일관된 도구 집합(read_file, write_file 등)을 제공합니다.
• 보안 우선 설계: 허용된 디렉터리 내에서만 작업이 이루어지도록 하고, 읽기 전용 마운트 등의 기능을 지원합니다.
• 유연한 통합: Docker, NPX, VS Code, Claude Desktop 등 다양한 환경과 호환됩니다.

MCP 파일 시스템 서버란?

MCP 파일 시스템 서버는 Model Context Protocol 프레임워크 내에서 파일 시스템 작업을 위해 특별히 구축된 Node.js 구현체입니다. 이 서버는 파일과 디렉터리를 안전하게 제어할 수 있는 포괄적인 도구 모음을 제공합니다.

MCP 파일 시스템 서버에서 사용할 수 있는 도구들

주요 기능을 간단히 정리하면 다음과 같습니다:

• read_file: UTF-8 인코딩으로 파일 내용을 읽음
• read_multiple_files: 여러 파일을 동시에 처리하며, 개별 실패에도 계속 진행
• write_file: 새 파일 생성 또는 기존 파일 덮어쓰기
• edit_file: 패턴 매칭을 통한 선택적 수정, 드라이런 및 Git 스타일의 diff 결과 제공
• create_directory: 상위 디렉터리 생성 옵션과 함께 디렉터리 생성
• list_directory: [FILE] 또는 [DIR] 접두어로 디렉터리 내 항목을 명확히 표시
• move_file: 파일 및 디렉터리 이동 또는 이름 변경
• search_files: 제외 패턴을 지원하며 재귀적으로 파일 검색
• get_file_info: 용량, 생성 시간, 권한 등 메타데이터 조회
• list_allowed_directories: 접근 가능한 모든 디렉터리 목록을 표시

이 모든 도구는 MCP 파일 시스템 작업의 인터페이스인 file://system 리소스를 통해 접근할 수 있습니다.

Claude와 함께하는 MCP 사용 예시

MCP가 실제로 어떻게 동작하는지 보여주기 위해, AI 어시스턴트 Claude와 MCP 파일 시스템 서버를 이용해 일반적인 파일 시스템 작업을 수행한 실제 예시를 살펴보겠습니다.

1단계: 허용된 디렉터리 목록 확인

가장 먼저 Claude가 접근할 수 있는 디렉터리가 어디인지 확인했습니다. list_allowed_directories 도구를 사용한 결과, 두 개의 허용된 위치가 표시되었습니다:

• /Users/arshia/Desktop
• /Users/arshia/Downloads

이를 통해 Claude의 작업이 이 두 디렉터리로 제한되어 있음을 확인할 수 있었고, 나머지 파일 시스템은 안전하게 보호되었습니다.

2단계: 디렉터리 내용 탐색

다음으로 list_directory 도구를 사용해 각 디렉터리에 어떤 파일이 있는지 살펴보았습니다. 결과는 다음과 같았습니다:

/Users/arshia/Desktop의 경우:

• [FILE] DS_Store
• [FILE] localized

/Users/arshia/Downloads의 경우:

• [FILE] DS_Store
• [FILE] localized
• [DIR] Visual Studio Code.app
• [FILE] shrek.txt
• [FILE] claudes diary.pages
• [FILE] diary.pdf

이로써 Downloads 디렉터리에 shrek.txt라는 파일이 있고, 그 외에도 여러 파일과 Visual Studio Code용 디렉터리가 있음을 알 수 있었습니다.

스크린샷: Desktop 및 Downloads 디렉터리의 list_directory 요청과 응답 화면

3단계: 파일 읽기 시도

shrek.txt를 확인한 후, read_file 도구를 이용해 파일 내용을 읽으려고 했습니다. 처음에는 shrek.txt라는 파일명만 제공하면 허용된 디렉터리에서 알아서 검색해줄 것이라 생각했습니다.

하지만 다음과 같은 오류가 발생했습니다:
“Access denied – path outside allowed directories: /shrek.txt not in /Users/arshia/Desktop, /Users/arshia/Downloads.”
이 오류는 MCP가 보안을 위해 전체 파일 경로를 요구하기 때문에 발생한 것입니다.

이미지 2: 에러 메시지가 표시된 read_file 실패 시도 스크린샷

4단계: 파일 읽기 성공

방법을 바로잡고 read_file 도구에 전체 경로 /Users/arshia/Downloads/shrek.txt를 입력하자, 이번에는 작업이 성공적으로 이루어졌고 파일의 내용이 반환되었습니다:

Request
{
  `path`: `/Users/arshia/Downloads/shrek.txt`
}
Response

Can you see what im writing here? If you do check this out: 

⢀⡴⠑⡄⠀⠀⠀⠀⠀⠀⠀⣀⣀⣤⣤⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠸⡇⠀⠿⡀⠀⠀⠀⣀⡴⢿⣿⣿⣿⣿⣿⣿⣿⣷⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠑⢄⣠⠾⠁⣀⣄⡈⠙⣿⣿⣿⣿⣿⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⢀⡀⠁⠀⠀⠈⠙⠛⠂⠈⣿⣿⣿⣿⣿⠿⡿⢿⣆⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⢀⡾⣁⣀⠀⠴⠂⠙⣗⡀⠀⢻⣿⣿⠭⢤⣴⣦⣤⣹⠀⠀⠀⢀⢴⣶⣆ 
⠀⠀⢀⣾⣿⣿⣿⣷⣮⣽⣾⣿⣥⣴⣿⣿⡿⢂⠔⢚⡿⢿⣿⣦⣴⣾⠁⠸⣼⡿ 
⠀⢀⡞⠁⠙⠻⠿⠟⠉⠀⠛⢹⣿⣿⣿⣿⣿⣌⢤⣼⣿⣾⣿⡟⠉⠀⠀⠀⠀⠀ 
⠀⣾⣷⣶⠇⠀⠀⣤⣄⣀⡀⠈⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠉⠈⠉⠀⠀⢦⡈⢻⣿⣿⣿⣶⣶⣶⣶⣤⣽⡹⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⠉⠲⣽⡻⢿⣿⣿⣿⣿⣿⣿⣷⣜⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣷⣶⣮⣭⣽⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⣀⣀⣈⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠻⠿⠿⠿⠿⛉

Shrek

• 사용자가 쓴 글을 읽을 수 있는지를 묻는 질문
• Shrek의 얼굴을 표현한 ASCII 아트
• 마지막에 “Shrek”라는 텍스트

이 성공적인 작업을 통해 MCP가 허용된 디렉터리 내에서 올바른 경로를 제공할 경우 파일을 읽을 수 있음을 확인했습니다.

예시를 통해 알게 된 주요 교훈

이번 실습 예시는 MCP 사용과 관련해 다음과 같은 중요한 점을 보여줍니다:

1. 전체 경로 필수: read_file 같은 도구는 파일명만이 아니라 전체 경로를 필요로 합니다.
2. 샌드박스 보안의 효과: 첫 시도 실패를 통해 MCP의 보안 모델이 의도대로 작동함을 확인할 수 있었습니다.
3. 반복적 탐색이 효과적: 디렉터리 목록 도구를 사용하면 파일 시스템을 효율적으로 탐색할 수 있습니다.

MCP 구현을 위한 모범 사례

경험과 MCP 파일 시스템 서버의 특징을 바탕으로 다음과 같은 모범 사례를 권장합니다:

• 항상 권한 먼저 확인: 작업 전에 list_allowed_directories로 허용된 디렉터리를 확인하세요.
• 완전한 경로 사용: 전체 경로를 입력해 오류와 혼동을 방지하세요.
• 수정 시 드라이런 활용: edit_file을 사용할 때는 dryRun: true로 미리 변경 사항을 확인하세요.
• 부분 성공에 대비: read_multiple_files와 같은 도구는 일부 실패에도 계속 진행할 수 있습니다.
• 최소 권한 원칙 적용: 서버 설정 시 수정이 필요 없는 디렉터리는 읽기 전용 마운트로 제한하세요.

결론

Model Context Protocol(MCP)과 파일 시스템 서버는 제어된 환경에서 안전하게 파일 시스템 작업을 수행할 수 있는 견고한 방법을 제공합니다. Claude와의 예시를 통해 list_directory와 read_file 등의 도구 사용법과 전체 경로 활용, 권한 경계 인식 등 중요한 원칙을 실전에서 확인할 수 있었습니다.

여기서 소개한 모범 사례를 따르면, MCP를 활용해 파일 시스템 작업을 안전하게 애플리케이션이나 개발 워크플로우에 통합할 수 있습니다.

프로젝트에 MCP를 도입하려는 개발자라면, 공식 GitHub 문서에서 더욱 상세한 정보와 구현 가이드를 확인하실 수 있습니다.