Claude 와 Filesystem : Model Context Protocol(MCP) 실제 적용 사례

Claude Desktop에서 내 컴퓨터에 있는 파일을 제어해보자

Model Context Protocol에서 자주 언급되는 연동 사례 중에서 File System을 연동하는 케이스가 있어서 이 부분도 포스팅을 해보려고 합니다. LLM에서 내 Local의 File시스템을 검색하고, 관련된 정보를 얻는데 매우 유용한 MCP Server 가 되겠습니다.

소스의 레파지토리는 다음의 링크를 참고해주시길 바랍니다. https://github.com/modelcontextprotocol/servers/tree/HEAD/src/filesystem

Claude Deskop을 사용하다가 내 로컬안에 있는 파일 및 파일의 속성, 또는 일부 내용을 변경, 이동 등의 제어를 할수 있는 MCP Server가 있습니다.

Filesystem MCP Server

주요 특징

파일 읽기/쓰기
디렉토리 생성/나열/삭제
파일/디렉토리 이동
파일 검색
파일 메타데이터 가져오기

이 MCP 서버는 설정에서 정의된 디렉토리 하위의 디렉토리 또는 파일만 지원됩니다.

API 관련 설명

제어 기반

file://system: 파일 시스템 작업 인터페이스

주요 기능

읽기_파일
- 파일의 전체 내용 읽기
- 입력: path(문자열)
- UTF-8 인코딩으로 전체 파일 내용을 읽습니다.
여러 파일 읽기
- 여러 파일을 동시에 읽기
- 입력: paths(string[])
- 읽기에 실패해도 전체 작업이 중단되지는 않습니다.
쓰기_파일
- 새 파일을 만들거나 기존 파일을 덮어씁니다(이 경우 주의하세요)
- 입력:
  - path(문자열): 파일 위치
  - content(문자열): 파일 내용
편집_파일
- 고급 패턴 매칭 및 서식을 사용하여 선택적 편집을 수행합니다.
- 특징:
  - 줄 기반 및 다중 줄 콘텐츠 매칭
  - 들여쓰기 보존을 통한 공백 정규화
  - 올바른 위치 지정을 통한 여러 동시 편집
  - 들여쓰기 스타일 감지 및 보존
  - 컨텍스트가 포함된 Git 스타일 diff 출력
  - 드라이런 모드로 변경 사항 미리 보기
- 입력:
  - path(문자열): 편집할 파일
  - edits(배열): 편집 작업 목록
    - oldText(문자열): 검색할 텍스트(부분 문자열 가능)
    - newText(문자열): 바꿀 텍스트
  - dryRun(부울): 변경 사항을 적용하지 않고 미리 봅니다(기본값: false)
- 드라이런에 대한 자세한 diff 및 매치 정보를 반환하고, 그렇지 않은 경우 변경 사항을 적용합니다.
- 모범 사례: 변경 사항을 적용하기 전에 항상 dryRun을 먼저 사용하여 변경 사항을 미리 봅니다.
디렉토리 생성
- 새 디렉토리를 생성하거나 디렉토리가 존재하는지 확인하세요.
- 입력: path(문자열)
- 필요한 경우 상위 디렉토리를 생성합니다.
- 디렉토리가 있으면 자동으로 성공합니다.
목록_디렉토리
- [FILE] 또는 [DIR] 접두사를 사용하여 디렉토리 내용을 나열합니다.
- 입력: path(문자열)
이동_파일
- 파일 및 디렉토리 이동 또는 이름 변경
- 입력:
  - source(끈)
  - destination(끈)
- 대상이 존재하면 실패합니다.
검색_파일
- 재귀적으로 파일/디렉토리 검색
- 입력:
  - path(문자열): 시작 디렉토리
  - pattern(문자열): 검색 패턴
  - excludePatterns(string[]): 패턴을 제외합니다. Glob 형식이 지원됩니다.
- 대소문자 구분 없이 일치
- 일치 항목의 전체 경로를 반환합니다.
파일_정보_받기
- 자세한 파일/디렉토리 메타데이터 가져오기
- 입력: path(문자열)
- 보고:
  - 크기
  - 창조 시간
  - 수정된 시간
  - 접속 시간
  - 유형(파일/디렉토리)
  - 권한
허용된 디렉토리 목록
- 서버가 액세스할 수 있는 모든 디렉토리를 나열합니다.
- 입력이 필요하지 않습니다
- 보고:
  - 이 서버가 읽고 쓸 수 있는 디렉토리

Claude Desktop에 설치

claude_desktop_config.json에 내용을 추가하고, 재시작 합니다.
Docker의 경우, 샌드박스가 적용된 디렉터리를 /projects에 마운트하여 서버에 제공할 수 있습니다.

Docker

참고 : 모든 디렉터리는 기본적으로 /projects에 마운트해야 합니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

Docker Build

docker build -t mcp/filesystem -f src/filesystem/Dockerfile .

NPX

username의 이름을 변경하고, 접근을 허용하여 이용할 디렉토리를 정의합니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

실제 적용 화면

결론

Claude Desktop을 이용한 Local File에 직접 제어를 할 수 있는 방법에 대해서 알아보았습니다. 텍스트 생성 이외에도 코드, 이미지 , 데이터 파일 등의 다양한 생성 작업들이 더욱 증가할 것으로 보이고, 더이상 복사 및 붙여넣기의 한계로부터 대화를 통한 제어가 일반적으로 가는 추세 입니다. 더불어 실제 마켓 플레이스 Pulse를 보면 관련된 File System의 기능을 제공하는 매우 다양한 다른 서버들도 올라오는 것 같습니다.

어플리케이션 개발과 관련된 코드 양산 및 저장, 관련 이미지 파일 생성 까지 개발과 관련된 자동 코드 생성 등의 구성도 가능해질것으로 보입니다.
실질적인 사용이 가능한 유즈 케이스에 대해서 이후 좀더 포스팅 해보도록 하겠습니다.

게시됨

2025년 04월 11일

카테고리

작성자

choonzang

태그:

AI 파일제어, claude, Claude Desktop, Filesystem, MCP, Model Context Protocol, 파일시스템