Filesystem MCP 서버

Node.js 서버로, 파일 시스템 작업을 위한 Model Context Protocol(MCP)을 구현합니다.

기능

파일 읽기/쓰기
디렉토리 생성/조회/삭제
파일/디렉토리 이동
파일 검색
파일 메타데이터 가져오기
Roots를 통한 동적 디렉토리 접근 제어

디렉토리 접근 제어

서버는 유연한 디렉토리 접근 제어 시스템을 사용합니다. 디렉토리는 명령줄 인수 또는 Roots를 통해 동적으로 지정할 수 있습니다.

방법 1: 명령줄 인수

서버 시작 시 허용된 디렉토리를 지정합니다:

mcp-server-filesystem /path/to/dir1 /path/to/dir2

방법 2: MCP Roots (권장)

MCP Roots를 지원하는 클라이언트는 허용된 디렉토리를 동적으로 업데이트할 수 있습니다.

클라이언트가 서버에 Roots를 알리면, 서버 측의 모든 허용 디렉토리가 완전히 대체됩니다.

중요: 서버가 명령줄 인수 없이 시작되고 클라이언트가 Roots 프로토콜을 지원하지 않거나(또는 빈 Roots를 제공하는 경우), 서버는 초기화 중 오류를 발생시킵니다.

이 방법은 서버 재시작 없이 roots/list_changed 알림을 통해 런타임 디렉토리 업데이트가 가능하여, 보다 유연하고 현대적인 통합 경험을 제공하므로 권장됩니다.

작동 방식

서버의 디렉토리 접근 제어는 다음 흐름을 따릅니다:

서버 시작
- 서버는 명령줄 인수에서 제공된 디렉토리로 시작합니다(제공된 경우).
- 인수가 제공되지 않으면, 서버는 빈 허용 디렉토리로 시작합니다.
클라이언트 연결 및 초기화
- 클라이언트가 연결되어 initialize 요청을 capabilities와 함께 보냅니다.
- 서버는 클라이언트가 Roots 프로토콜을 지원하는지 확인합니다(capabilities.roots).
Roots 프로토콜 처리 (클라이언트가 Roots를 지원하는 경우)
- 초기화 시: 서버는 roots/list를 통해 클라이언트에 Roots를 요청합니다.
- 클라이언트는 설정된 Roots로 응답합니다.
- 서버는 모든 허용 디렉토리를 클라이언트의 Roots로 대체합니다.
- 런타임 업데이트 시: 클라이언트는 notifications/roots/list_changed를 보낼 수 있습니다.
- 서버는 업데이트된 Roots를 요청하고 허용 디렉토리를 다시 대체합니다.
폴백 동작 (클라이언트가 Roots를 지원하지 않는 경우)
- 서버는 명령줄 디렉토리만 계속 사용합니다.
- 동적 업데이트가 불가능합니다.
접근 제어
- 모든 파일 시스템 작업은 허용된 디렉토리로 제한됩니다.
- list_allowed_directories 도구를 사용하여 현재 디렉토리를 확인하세요.
- 서버는 작동을 위해 최소한 하나의 허용 디렉토리가 필요합니다.

참고: 서버는 args 또는 Roots를 통해 지정된 디렉토리 내에서만 작업을 허용합니다.

API

도구

read_text_file
- 파일의 전체 내용을 텍스트로 읽습니다.
- 입력:
  - path (string)
  - head (number, 선택 사항): 처음 N줄
  - tail (number, 선택 사항): 마지막 N줄
- 확장자와 관계없이 항상 파일을 UTF-8 텍스트로 처리합니다.
- head와 tail을 동시에 지정할 수 없습니다.
read_media_file
- 이미지 또는 오디오 파일을 읽습니다.
- 입력:
  - path (string)
- 파일을 스트리밍하고 해당 MIME 유형과 함께 base64 데이터를 반환합니다.
read_multiple_files
- 여러 파일을 동시에 읽습니다.
- 입력: paths (string[])
- 실패한 읽기 작업은 전체 작업을 중단하지 않습니다.
write_file
- 새 파일을 만들거나 기존 파일을 덮어씁니다(주의해서 사용하세요).
- 입력:
  - path (string): 파일 위치
  - content (string): 파일 내용
edit_file
- 고급 패턴 매칭 및 서식을 사용하여 선택적으로 편집합니다.
- 기능:
  - 줄 기반 및 여러 줄 콘텐츠 매칭
  - 들여쓰기 유지와 함께 공백 정규화
  - 올바른 위치 지정을 통한 여러 동시 편집
  - 들여쓰기 스타일 감지 및 유지
  - 컨텍스트가 포함된 Git 스타일 diff 출력
  - dry run 모드로 변경 사항 미리보기
- 입력:
  - path (string): 편집할 파일
  - edits (array): 편집 작업 목록
    - oldText (string): 검색할 텍스트(부분 문자열 가능)
    - newText (string): 대체할 텍스트
  - dryRun (boolean): 변경 사항을 적용하지 않고 미리보기(기본값: false)
- dry run의 경우 자세한 diff 및 매칭 정보를 반환하고, 그렇지 않으면 변경 사항을 적용합니다.
- 모범 사례: 변경 사항을 적용하기 전에 항상 dryRun을 먼저 사용하여 미리보세요.
create_directory
- 새 디렉토리를 만들거나 존재하는지 확인합니다.
- 입력: path (string)
- 필요한 경우 상위 디렉토리를 만듭니다.
- 디렉토리가 이미 존재하면 조용히 성공합니다.
list_directory
- [FILE] 또는 [DIR] 접두사와 함께 디렉토리 내용을 나열합니다.
- 입력: path (string)
list_directory_with_sizes
- [FILE] 또는 [DIR] 접두사와 함께 디렉토리 내용을 나열하고, 파일 크기를 포함합니다.
- 입력:
  - path (string): 나열할 디렉토리 경로
  - sortBy (string, 선택 사항): "name" 또는 "size"로 항목 정렬(기본값: "name")
- 파일 크기 및 요약 통계와 함께 상세 목록을 반환합니다.
- 총 파일, 디렉토리 및 결합된 크기를 표시합니다.
move_file
- 파일 및 디렉토리를 이동하거나 이름을 바꿉니다.
- 입력:
  - source (string)
  - destination (string)
- 대상이 이미 존재하면 실패합니다.
search_files
- 패턴과 일치하거나 일치하지 않는 파일/디렉토리를 재귀적으로 검색합니다.
- 입력:
  - path (string): 시작 디렉토리
  - pattern (string): 검색 패턴
  - excludePatterns (string[]): 제외할 패턴
- Glob 스타일 패턴 매칭
- 일치하는 항목의 전체 경로를 반환합니다.
directory_tree
- 디렉토리 내용의 재귀적 JSON 트리 구조를 가져옵니다.
- 입력:
  - path (string): 시작 디렉토리
  - excludePatterns (string[]): 제외할 패턴. Glob 형식이 지원됩니다.
- 반환:
  - 각 항목에 다음이 포함된 JSON 배열:
    - name (string): 파일/디렉토리 이름
    - type ('file'|'directory'): 항목 유형
    - children (array): 디렉토리에만 존재
      - 빈 디렉토리의 경우 빈 배열
      - 파일의 경우 생략
- 가독성을 위해 2칸 들여쓰기로 출력이 서식 지정됩니다.
get_file_info
- 자세한 파일/디렉토리 메타데이터를 가져옵니다.
- 입력: path (string)
- 반환:
  - 크기
  - 생성 시간
  - 수정 시간
  - 접근 시간
  - 유형 (파일/디렉토리)
  - 권한
list_allowed_directories
- 서버가 액세스할 수 있는 모든 디렉토리를 나열합니다.
- 입력 불필요
- 반환:
  - 이 서버가 읽고 쓸 수 있는 디렉토리

도구 주석 (MCP 힌트)

이 서버는 각 도구에 MCP ToolAnnotations을 설정하여 클라이언트가 다음을 수행할 수 있도록 합니다:

읽기 전용 도구와 쓰기 가능 도구를 구분합니다.
어떤 쓰기 작업이 멱등적(동일한 인수로 재시도해도 안전)인지 이해합니다.
파괴적(데이터를 덮어쓰거나 크게 변경)일 수 있는 작업을 강조합니다.

파일 시스템 도구의 매핑은 다음과 같습니다:

도구	readOnlyHint	idempotentHint	destructiveHint	참고
`read_text_file`	`true`	–	–	순수 읽기
`read_media_file`	`true`	–	–	순수 읽기
`read_multiple_files`	`true`	–	–	순수 읽기
`list_directory`	`true`	–	–	순수 읽기
`list_directory_with_sizes`	`true`	–	–	순수 읽기
`directory_tree`	`true`	–	–	순수 읽기
`search_files`	`true`	–	–	순수 읽기
`get_file_info`	`true`	–	–	순수 읽기
`list_allowed_directories`	`true`	–	–	순수 읽기
`create_directory`	`false`	`true`	`false`	동일한 디렉토리를 다시 생성하는 것은 무효 연산
`write_file`	`false`	`true`	`true`	기존 파일을 덮어씁니다
`edit_file`	`false`	`false`	`true`	편집을 다시 적용하면 실패하거나 이중 적용될 수 있음
`move_file`	`false`	`false`	`true`	원본 파일을 삭제합니다

참고: MCP 사양에 정의된 대로 idempotentHint와 destructiveHint는 readOnlyHint가 false인 경우에만 의미가 있습니다.

Claude Desktop과 함께 사용하기

claude_desktop_config.json에 다음을 추가하세요:

참고: 서버에 샌드박스 디렉토리를 제공하려면 /projects에 마운트하면 됩니다. ro 플래그를 추가하면 디렉토리가 서버에서 읽기 전용이 됩니다.

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"
      ]
    }
  }
}

NPX

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

Windows에서는 cmd /c를 사용하여 npx를 실행하세요:

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

VS Code와 함께 사용하기

빠른 설치를 위해 아래 설치 버튼을 클릭하세요...

수동 설치의 경우 다음 방법 중 하나를 사용하여 MCP 서버를 구성할 수 있습니다:

방법 1: 사용자 구성 (권장) 구성을 사용자 수준 MCP 구성 파일에 추가합니다. 명령 팔레트(Ctrl + Shift + P)를 열고 MCP: Open User Configuration을 실행하세요. 그러면 서버 구성을 추가할 수 있는 사용자 mcp.json 파일이 열립니다.

방법 2: 작업 영역 구성 또는 작업 영역에 .vscode/mcp.json이라는 파일에 구성을 추가할 수 있습니다. 이렇게 하면 구성을 다른 사람과 공유할 수 있습니다.

VS Code의 MCP 구성에 대한 자세한 내용은 공식 VS Code MCP 문서를 참조하세요.

서버에 샌드박스 디렉토리를 제공하려면 /projects에 마운트하면 됩니다. ro 플래그를 추가하면 디렉토리가 서버에서 읽기 전용이 됩니다.

Docker

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

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Windows에서는 다음을 사용하세요:

{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

[truncated ...]

DrDexter6000/talking-cli

talking-cli란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

미리보기

문서

Filesystem MCP 서버

기능

디렉토리 접근 제어

방법 1: 명령줄 인수

방법 2: MCP Roots (권장)

작동 방식

API

도구

도구 주석 (MCP 힌트)

Claude Desktop과 함께 사용하기

Docker

NPX

VS Code와 함께 사용하기

Docker

NPX

관련 스킬

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep