/ 디렉터리 / 플레이그라운드 / Filesystem
← 모든 서버 ↗ GitHub
● 공식 modelcontextprotocol ⚡ 바로 사용

Filesystem

제작: modelcontextprotocol · modelcontextprotocol/servers

Claude에 한 개 디렉토리에 대한 샌드박스된 읽기/쓰기 액세스를 제공합니다 — 셸 명령 없이 코드 리팩토링, 문서 처리, 로그 분석을 수행합니다.

레퍼런스 파일시스템 MCP입니다. 하나 이상의 디렉토리를 루트로 마운트하며, 모든 툴 호출이 해당 루트에 엄격히 바인드되므로 Claude는 ../를 통해 SSH 키에 접근할 수 없습니다. 텍스트, 바이너리, 검색, 라인 레벨 편집을 지원합니다. 가장 많이 설치되는 MCP인 이유가 있습니다.

▶ 데모 보기 📦 설치 💡 사용 사례

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

filesystem.replay ▶ 준비됨
0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

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

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

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

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  ]
}

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

~/.config/zed/settings.json
{
  "context_servers": {
    "filesystem": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/workspace"
        ]
      }
    }
  }
}

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

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace

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

사용 사례

실전 활용법: Filesystem

전체 코드베이스에서 함수를 리팩토링하되 깨지 않는 방법

👤 많은 파일에서 사용되는 API를 이름 변경하거나 재구성하는 엔지니어 ⏱ ~20 min intermediate

언제 쓸까: 함수 이름을 바꾸거나, 서명을 변경하거나, 헬퍼를 인라인화해야 하며, 저장소의 30개 이상 파일에서 사용되는 경우입니다.

사전 조건
  • git 워킹 트리 정리됨 — git status에 스테이징된 항목이 없음 — git diff로 검토하고 필요시 git restore할 수 있음
  • 저장소에 범위가 지정된 파일시스템 루트 — npx -y @modelcontextprotocol/server-filesystem /abs/path/to/repo로 시작
흐름
  1. 모든 호출 사이트 찾기
    코드베이스에서 getUserProfile(의 모든 사용처를 검색합니다. 파일별로 일치 항목을 그룹화하고 파일당 개수를 알려주세요.✓ 복사됨
    → 테스트와 소스 구분을 제외한 일치 개수가 있는 파일 목록
  2. 한 파일에서 편집 드라이런
    src/api/users.ts에서 편집 모습을 보여주세요 — 전체 파일이 아닌 diff입니다. 아직 작성하지 마세요.✓ 복사됨
    → 최소한의 diff 패치, 전체 파일 재작성 아님
  3. 모든 파일에 적용하고 보고
    1단계의 모든 파일에 동일한 변환을 적용합니다. write_file(덮어쓰기)이 아닌 edit_file(라인 레벨)을 사용하세요. 패턴이 깔끔하게 일치하지 않은 파일을 알려주세요.✓ 복사됨
    → 파일별 성공/스킵 로그

결과: 테스트를 실행할 수 있는 집중된 리뷰 가능한 git diff — 예상치 못한 전체 파일 재작성 없음.

함정
  • Claude가 write_file을 사용하고 편집이 복잡할 때 파일의 절반을 무음으로 삭제함 — 제자리 변경에는 edit_file을 명시적으로 요구하고, 새로 생성되는 파일에만 write_file을 허용하세요
  • 일치가 관련 없는 코드를 적중 (예: getUserProfileAvatar) — 검색을 고정합니다: 뒤에 오는 괄호가 있는 getUserProfile(를 사용하거나 단어 경계 정규식을 사용하세요
함께 쓰기: git · github

프로덕션 로그 파일을 로컬에서 읽어 충돌 진단

👤 디스크에 로그가 있는 온콜 엔지니어 ⏱ ~15 min beginner

언제 쓸까: 고객 사건에서 로그 번들을 다운로드했고 grep 실력 없이 바늘을 찾아야 하는 경우입니다.

사전 조건
  • 디스크의 로그 — 전용 /incidents/<ticket>/ 폴더 아래에 다운로드/압축 해제
흐름
  1. 구조적 개요 얻기
    /incidents/TICKET-1234/ 아래의 파일을 나열합니다. 각 로그 파일에 대해 크기와 내부의 첫 번째 + 마지막 타임스탬프를 표시하세요.✓ 복사됨
    → 시간 제한 인벤토리
  2. 오류 클러스터 찾기
    모든 .log 파일에서 ERROR|FATAL|panic 패턴을 검색합니다. 가장 높은 밀도의 적중을 가진 10분을 알려주세요.✓ 복사됨
    → 시간이 아닌 분 단위로 좁혀진 시간 창
  3. 첫 번째 치명 오류 주변 컨텍스트 읽기
    app.log의 첫 번째 FATAL 라인 주변 50줄의 컨텍스트를 읽습니다. 충돌하기 바로 전에 시스템이 무엇을 하고 있었는지 설명하세요.✓ 복사됨
    → 로그 역류가 아닌 내러티브 재구성

결과: 사건 문서에 붙여 넣을 수 있는 5문장 타임라인.

함정
  • 큰 로그 파일(>50MB)은 모델 컨텍스트를 초과합니다 — head/tail + grep 스타일 추출만 요청하세요. 큰 항목에 대해 Claude에게 '전체 파일 읽기'를 요청하지 마세요
함께 쓰기: sentry · github

PDF, Markdown, 문서 폴더에 대한 질문하기

👤 참조 자료가 많은 연구자, 분석가 ⏱ ~15 min beginner

언제 쓸까: 폴더에 50개의 논문/계약/보고서가 있고 하나의 특정 사실을 추출하거나 비교해야 하는 경우입니다.

사전 조건
  • 한 폴더에 정리된 문서 — 한 디렉토리 또는 얕은 트리로 평면화하세요. Claude는 더 평평한 구조를 더 잘 순회합니다
흐름
  1. 폴더 인덱싱
    /research/2026-market-study/ 아래의 모든 파일을 나열합니다. 각 파일에 대해 파일명과 첫 200자를 알려주세요.✓ 복사됨
    → 빠른 미리보기가 있는 인벤토리
  2. 실제 질문하기
    이 문서 중 '계약적 배상 한도'를 언급하는 것은 어느 것입니까? 각 적중에 대해 정확한 문장을 인용하고 파일명을 알려주세요.✓ 복사됨
    → 그냥 분위기가 아닌 파일명이 있는 인용
  3. 문서 간 종합
    이를 가진 3개 문서 전반에서 배상 한도를 비교합니다. 어느 것이 우리에게 가장 유리하고 그 이유는 무엇입니까?✓ 복사됨
    → 직접 인용과 함께 나란히 비교

결과: 30초 안에 검증할 수 있는 파일명+인용 인용이 있는 답변.

함정
  • 스캔된 PDF는 이미지 기반 — 콘텐츠별 검색 실패 — 먼저 OCR을 실행하거나 (예: ocrmypdf) 전용 PDF MCP를 사용하세요. 시작하기 전에 '검색 불가능' 파일을 기록하세요
  • Claude가 요약하고 출처 귀속을 잃음 — 항상 프롬프트에서 파일명 + 정확한 인용을 요구하세요. 이 없는 답변을 거부하세요
함께 쓰기: memory

한 번의 채팅으로 사양에서 새 프로젝트 스캐폴딩

👤 새로운 서비스/라이브러리/프로토타입을 시작하는 엔지니어 ⏱ ~10 min beginner

언제 쓸까: 한 단락의 사양이 있고 템플릿 저장소에서 복사하지 않고 보일러플레이트(폴더, package.json, README, 테스트)를 구체화하려는 경우입니다.

사전 조건
  • 빈 대상 디렉토리 — mkdir /projects/newthing을 실행하고 파일시스템 루트를 해당 상위 디렉토리로 가리킵니다
흐름
  1. 작성 전 레이아웃 동의
    X를 수행하는 TypeScript Node CLI 도구를 원합니다. 폴더 구조를 제안하고 한 줄 목적으로 생성할 모든 파일을 나열하세요. 아직 작성하지 마세요.✓ 복사됨
    → 파일별 계획 — 디스크가 수정되기 전에 거부할 수 있습니다
  2. 파일 작성
    좋아 보입니다. /projects/newthing/ 아래에 모든 파일을 생성하세요. 최소한의 관용적 콘텐츠를 사용하세요 — 자리 표시자 주석 없음, 'TODO' 스텁 없음.✓ 복사됨
    → 디스크의 파일, 첫 시도에 깨끗하게 컴파일/린트됨
  3. 다시 읽어서 확인
    방금 생성한 모든 파일을 읽고 프로젝트가 tsc --noEmit과 npm test를 통과할 것임을 확인하세요. 통과하지 않는 것을 수정하세요.✓ 복사됨
    → 손 흔들기가 아닌 구체적인 수정으로 자체 확인

결과: 30분 대신 3분 안에 작동하는 스켈레톤 프로젝트.

함정
  • Claude가 파일을 작성하고 세션 중간에 작성한 내용을 잊음 — 먼저 파일 계획을 작성한 후 작성하도록 하세요. 끝에서 다시 읽으면 드리프트를 포착합니다
함께 쓰기: git · github

조합

다른 MCP와 조합해 10배 효율

filesystem + github

로컬에서 파일을 편집하고 채팅을 떠나지 않고 브랜치를 푸시하고 PR을 엽니다

src/utils/format.ts:42의 오타를 수정한 후, 새 브랜치 fix/typo-format을 푸시하고 'fix: typo in format.ts' 제목의 PR을 엽니다.✓ 복사됨
filesystem + git

편집하고, diff를 검토하고, 커밋하기 — 모두 Claude 내에서

src/의 3개 중복 헬퍼를 하나의 공유 유틸로 리팩토링합니다. 커밋하기 전에 diff를 보여주고, 깨끗한 메시지로 커밋하세요.✓ 복사됨
filesystem + sqlite

디스크에서 CSV를 읽고 분석을 위해 SQLite 테이블에 로드합니다

/data/orders.csv를 읽고, 타입을 추론하고, /data/analysis.db에 orders 테이블로 로드하세요.✓ 복사됨

도구

이 MCP가 노출하는 것

도구입력언제 호출비용
read_text_file path: str, head?: int, tail?: int 텍스트 파일을 읽습니다. head/tail을 사용하여 큰 파일 로드를 피하세요 무료
read_media_file path: str 이미지, PDF, 오디오를 멀티모달 입력을 위해 base64로 읽습니다 무료
read_multiple_files paths: str[] 관련 파일을 한 번에 배치 읽기 (N번 호출보다 빠름) 무료
write_file path: str, content: str 새 파일을 생성하거나 완전히 바꾸기 — 파괴적 무료
edit_file path: str, edits: [{oldText, newText}], dryRun?: bool 더 안전한 라인 레벨 편집. 기존 파일의 경우 항상 write_file보다 선호합니다 무료
create_directory path: str 디렉토리 생성 (재귀적, mkdir -p 스타일) 무료
list_directory path: str 비재귀적 ls 무료
directory_tree path: str 프로젝트 구조의 한 눈에 보는 개요 무료
move_file source: str, destination: str 이름 바꾸기 또는 이동 무료
search_files path: str, pattern: str, excludePatterns?: str[] 재귀적 콘텐츠 검색 — grep과 같음 무료
get_file_info path: str 콘텐츠를 읽지 않고 파일 통계 무료
list_allowed_directories none 서버가 시작된 루트 확인 무료

비용 및 제한

운영 비용

API 쿼터
무제한 — 로컬 I/O입니다
호출당 토큰
파일 크기에 따라 다름 — 파일 콘텐츠 4자당 약 1 토큰 예산
금액
무료
팁
전체 파일을 읽는 대신 search_files와 head/tail을 사용하세요. 컨텍스트에 덤프된 2MB 로그는 약 500k 토큰의 비용이 듭니다.

보안

권한, 시크릿, 파급범위

최소 스코프: filesystem-read filesystem-write (변경하는 경우)
자격 증명 저장: 자격 증명 없음 — 액세스는 인수로 전달된 루트 디렉토리를 통함
데이터 외부 송신: 서버에서 없음 — 파일 콘텐츠는 MCP 클라이언트를 통해 컨텍스트로 LLM 제공자로 전송됩니다
절대 부여 금지: root=/ root=$HOME root=/etc 또는 /var

문제 해결

자주 발생하는 오류와 해결

오류: 경로가 허용된 디렉토리 내에 없습니다

파일이 시작 시 전달된 모든 루트 외부입니다. 추가 루트 인수로 서버를 다시 시작하거나 list_allowed_directories를 사용하여 실제로 허용되는 것을 확인하세요.

확인: Claude에게 `list_allowed_directories` 호출을 요청하세요
ENOENT: 그러한 파일 또는 디렉토리가 없습니다

경로 오타 또는 잘못된 작업 디렉토리 가정. 루트에서 directory_tree를 사용하여 실제 레이아웃을 확인하세요.

edit_file: oldText를 찾을 수 없습니다

oldText 패턴은 공백을 포함하여 정확히 일치해야 합니다. Claude에게 먼저 read_text_file을 요청하고 정확한 부분 문자열을 복사하세요.

거대한 파일이 클라이언트를 중지시킵니다

몇 MB보다 큰 전체 파일을 읽지 마세요. read_text_file에서 head/tail 매개변수를 사용하거나 search_files를 사용하여 관련 라인만 찾으세요.

확인: 먼저 `get_file_info`로 파일 크기 확인

대안

Filesystem 다른 것과 비교

대안언제 쓰나단점/장점
git MCP원시 파일 I/O가 아닌 버전 인식 작업(diff, blame, log)이 필요한 경우입니다쓰기 도구 없음. git 렌즈를 통한 읽기 전용
GitHub MCP파일이 원격 저장소에 있고 로컬 클론을 원하지 않는 경우입니다PAT 필요. 파일당 지연 시간이 로컬 디스크보다 훨씬 높습니다
JetBrains MCP편집이 리팩토링 도구를 사용하여 실행 중인 IDE 인스턴스에 표시되기를 원하는 경우입니다JetBrains IDE가 열려 있어야 함. 순수 파일시스템보다 무거움

더 보기

리소스

📖 GitHub에서 공식 README 읽기

🐙 열린 이슈 보기

🔍 400+ MCP 서버 및 Skills 전체 보기