Filesystem MCP란?

Filesystem MCP는 Anthropic이 공식 제공하는 MCP 서버로, AI 모델이 로컬 파일 시스템에 안전하게 접근할 수 있도록 합니다. 파일 읽기, 쓰기, 디렉토리 탐색, 파일 검색 등 개발자가 일상적으로 수행하는 파일 작업을 AI가 대신 처리합니다.

이전 편에서 MCP 서버를 직접 만들어 봤다면, 이번에는 이미 만들어진 공식 서버를 활용하는 방법을 배웁니다.

!mcp-guide-03-filesystem 본문 이미지 1

설치 및 설정

Filesystem MCP는 공식 npm 패키지로 배포되기 때문에 별도의 컴파일이나 Git 클론이 필요 없습니다. Claude Code의 MCP 설정 파일에 항목 하나만 추가하면 즉시 동작하며, 허용 디렉토리를 args의 마지막 위치 파라미터로 넘기는 구조입니다. 운영체제별 경로 표기법만 주의하면 되고, 이 섹션에서는 Linux/macOS 표준 설정과 Windows 설정을 각각 소개합니다.

1단계: MCP 설정에 Filesystem 서버 등록

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/home/user/projects",
"/home/user/documents"
]
}
}
}

args의 마지막 항목들이 허용 디렉토리입니다. 이 범위 밖의 파일에는 접근할 수 없어 보안이 유지됩니다.

2단계: Windows 환경 설정

Windows에서는 경로 형식에 주의합니다.

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"C:/Users/dev/projects",
"D:/workspace"
]
}
}
}

!파일 시스템 자동 탐색

제공되는 도구 목록

Filesystem MCP가 제공하는 11가지 도구입니다.

!mcp-guide-03-filesystem 본문 이미지 2

실전 활용 예시

실제로 Filesystem MCP를 얼마나 잘 쓰는지는 "어떤 도구를 명시적으로 호출하는가"가 아니라 "자연어로 어떤 요청을 던지는가"에 달려 있습니다. Claude Code는 요청 문장을 분석해 적절한 도구를 자동으로 선택하기 때문에, 개발자는 SQL 같은 명령어가 아닌 의도 문장만 기술하면 됩니다. 아래 세 가지는 현장에서 가장 자주 등장하는 패턴입니다.

프로젝트 구조 파악

Claude Code에서 자연어로 요청하면 Filesystem MCP가 자동으로 적절한 도구를 선택합니다.

# Claude Code에서 실행
claude "이 프로젝트의 전체 디렉토리 구조를 보여줘"
→ directory_tree 도구 자동 호출

claude "src 폴더에서 미완료 주석이 포함된 파일을 찾아줘"
→ search_files 도구 자동 호출

여러 파일 비교 분석

claude "package.json과 package-lock.json의 의존성 버전 차이를 분석해줘"
→ read_multiple_files로 두 파일을 동시에 읽고 비교

자동 리팩토링

claude "src/utils 폴더의 모든 .ts 파일에서 console.log를 logger.debug로 교체해줘"
→ search_files로 대상 파일 찾기 → read_file로 내용 확인 → edit_file로 수정

!Claude Code에서 파일 작업

보안 설정 가이드

Filesystem MCP의 보안은 허용 디렉토리 화이트리스트 방식으로 동작합니다.

{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/home/user/projects/my-app"
]
}
}
}

보안 체크리스트를 반드시 확인하세요.

• 프로젝트 디렉토리만 허용하고 홈 디렉토리 전체(~)는 피합니다
• .env, credentials.json 등 민감한 파일이 있는 디렉토리는 제외합니다
• 읽기 전용이 필요한 경우 --read-only 플래그를 사용합니다
• 심볼릭 링크가 허용 범위 밖으로 연결되지 않는지 확인합니다

# 읽기 전용 모드 (쓰기/수정/이동/삭제 차단)
npx -y @modelcontextprotocol/server-filesystem --read-only /path/to/dir

자주 묻는 질문

Q: 파일 크기 제한이 있나요?

기본적으로 제한은 없지만, 매우 큰 파일(100MB+)은 메모리 문제가 발생할 수 있습니다. 대용량 파일은 스트리밍 방식의 커스텀 서버를 고려하세요.

Q: 바이너리 파일도 읽을 수 있나요?

텍스트 기반 파일에 최적화되어 있습니다. 이미지나 바이너리 파일은 메타데이터(크기, 수정일) 조회만 권장합니다.

Q: 여러 프로젝트에서 동시에 사용할 수 있나요?

네, args에 여러 디렉토리를 나열하면 됩니다. 프로젝트별로 별도의 MCP 인스턴스를 설정할 수도 있습니다.

다음 단계

파일 시스템 자동화를 익혔다면, 다음 편에서는 GitHub MCP를 활용한 PR/이슈/코드 리뷰 자동화를 다룹니다.

---

MCP 실전 가이드 시리즈

MCP란 무엇인가

첫 MCP 서버 만들기

Filesystem MCP 실전 (현재 글)

GitHub MCP 자동화

PostgreSQL MCP 쿼리

Slack MCP 커뮤니케이션

Linear MCP 프로젝트 관리

커스텀 MCP 서버

MCP 보안 가이드

MCP 생태계 총정리

AI K LINK의 Kit MCP 추천 목록에서 Filesystem MCP를 포함한 공식 서버를 탐색하세요. 빠른 시작 가이드에서 전체 설정 과정을 확인할 수 있습니다.