Filesystem MCP 서버

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

npm에 @modelcontextprotocol/server-filesystem으로 게시되었습니다.

기능

• 파일 읽기/쓰기

• 디렉토리 생성/목록/삭제

• 파일/디렉토리 이동

• 파일 검색

• 파일 메타데이터 가져오기

• Roots를 통한 동적 디렉토리 접근 제어

디렉토리 접근 제어

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

방법 1: 명령줄 인수

서버 시작 시 허용된 디렉토리 지정:

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

방법 2: MCP Roots (권장)

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

클라이언트가 서버에 알린 Roots는 제공될 때 서버 측 허용 디렉토리를 완전히 대체합니다.

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

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

작동 방식

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

1. 서버 시작

   • 서버는 명령줄 인수(제공된 경우)의 디렉토리로 시작합니다.

   • 인수가 제공되지 않으면 서버는 빈 허용 디렉토리로 시작합니다.

2. 클라이언트 연결 및 초기화

   • 클라이언트가 연결되고 기능과 함께 initialize 요청을 보냅니다.

   • 서버는 클라이언트가 roots 프로토콜(capabilities.roots)을 지원하는지 확인합니다.

3. Roots 프로토콜 처리 (클라이언트가 roots를 지원하는 경우)

   • 초기화 시: 서버는 roots/list를 통해 클라이언트에 roots를 요청합니다.

   • 클라이언트는 구성된 roots로 응답합니다.

   • 서버는 모든 허용 디렉토리를 클라이언트의 roots로 대체합니다.

   • 런타임 업데이트 시: 클라이언트는 notifications/roots/list_changed를 보낼 수 있습니다.

   • 서버는 업데이트된 roots를 요청하고 허용 디렉토리를 다시 대체합니다.

4. 대체 동작 (클라이언트가 roots를 지원하지 않는 경우)

   • 서버는 명령줄 디렉토리만 계속 사용합니다.

   • 동적 업데이트는 불가능합니다.

5. 접근 제어

   • 모든 파일 시스템 작업은 허용된 디렉토리로 제한됩니다.

   • list_allowed_directories 도구를 사용하여 현재 디렉토리를 확인합니다.

   • 서버가 작동하려면 최소한 하나의 허용 디렉토리가 필요합니다.

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

API

도구

• read_text_file

  • 파일의 전체 내용을 텍스트로 읽습니다.

  • 입력:

    • path (문자열)

    • head (숫자, 선택 사항): 처음 N줄

    • tail (숫자, 선택 사항): 마지막 N줄

  • 확장자와 관계없이 항상 파일을 UTF-8 텍스트로 처리합니다.

  • head와 tail을 동시에 지정할 수 없습니다.

• read_media_file

  • 파일을 읽고 MIME 유형과 함께 base64로 인코딩된 콘텐츠 블록으로 반환합니다.

  • 입력:

    • path (문자열)

  • 파일을 스트리밍하고 해당 MIME 유형과 함께 base64 데이터를 반환합니다. 이미지 및 오디오 파일은 image/audio 콘텐츠로 반환되고, 다른 모든 파일 유형은 임베디드 resource (임의의 바이너리 데이터에 대한 유효한 MCP 콘텐츠 블록)로 반환됩니다.

• read_multiple_files

  • 여러 파일을 동시에 읽습니다.

  • 입력: paths (문자열[])

  • 읽기 실패가 전체 작업을 중단시키지 않습니다.

• write_file

  • 새 파일을 생성하거나 기존 파일을 덮어씁니다(주의해서 사용).

  • 입력:

    • path (문자열): 파일 위치

    • content (문자열): 파일 내용

• edit_file

  • 고급 패턴 매칭 및 서식을 사용하여 선택적으로 편집합니다.

  • 기능:

    • 줄 기반 및 여러 줄 콘텐츠 매칭

    • 들여쓰기 보존을 통한 공백 정규화

    • 올바른 위치 지정을 통한 여러 동시 편집

    • 들여쓰기 스타일 감지 및 보존

    • 컨텍스트가 포함된 Git 스타일 diff 출력

    • 드라이 런 모드로 변경 사항 미리보기

  • 입력:

    • path (문자열): 편집할 파일

    • edits (배열): 편집 작업 목록

      • oldText (문자열): 검색할 텍스트 (부분 문자열 가능)

      • newText (문자열): 대체할 텍스트

    • dryRun (부울): 적용하지 않고 변경 사항 미리보기 (기본값: false)

  • 드라이 런의 경우 상세 diff 및 매치 정보를 반환하고, 그렇지 않으면 변경 사항을 적용합니다.

  • 모범 사례: 변경 사항을 적용하기 전에 항상 dryRun을 먼저 사용하여 미리보세요.

• create_directory

  • 새 디렉토리를 생성하거나 존재하는지 확인합니다.

  • 입력: path (문자열)

  • 필요한 경우 상위 디렉토리를 생성합니다.

  • 디렉토리가 이미 존재하면 자동으로 성공합니다.

• list_directory

  • 디렉토리 내용을 [FILE] 또는 [DIR] 접두사와 함께 나열합니다.

  • 입력: path (문자열)

• list_directory_with_sizes

  • 디렉토리 내용을 [FILE] 또는 [DIR] 접두사와 함께 파일 크기를 포함하여 나열합니다.

  • 입력:

    • path (문자열): 나열할 디렉토리 경로

    • sortBy (문자열, 선택 사항): "name" 또는 "size"로 항목 정렬 (기본값: "name")

  • 파일 크기 및 요약 통계와 함께 상세 목록을 반환합니다.

  • 총 파일, 디렉토리 및 결합된 크기를 표시합니다.

• move_file

  • 파일 및 디렉토리를 이동하거나 이름을 바꿉니다.

  • 입력:

    • source (문자열)

    • destination (문자열)

  • 대상이 이미 존재하면 실패합니다.

• search_files

  • 패턴과 일치하거나 일치하지 않는 파일/디렉토리를 재귀적으로 검색합니다.

  • 입력:

    • path (문자열): 시작 디렉토리

    • pattern (문자열): 검색 패턴

    • excludePatterns (문자열[]): 제외할 패턴

  • Glob 스타일 패턴 매칭

  • 일치하는 항목의 전체 경로를 반환합니다.

• directory_tree

  • 디렉토리 내용의 재귀적 JSON 트리 구조를 가져옵니다.

  • 입력:

    • path (문자열): 시작 디렉토리

    • excludePatterns (문자열[]): 제외할 패턴. Glob 형식이 지원됩니다.

  • 반환:

    • 각 항목이 다음을 포함하는 JSON 배열:

      • name (문자열): 파일/디렉토리 이름

      • type ('file'|'directory'): 항목 유형

      • children (배열): 디렉토리에만 존재

        • 빈 디렉토리의 경우 빈 배열

        • 파일의 경우 생략

  • 출력은 가독성을 위해 2-공백 들여쓰기로 서식이 지정됩니다.

• get_file_info

  • 파일/디렉토리의 상세 메타데이터를 가져옵니다.

  • 입력: path (문자열)

  • 반환:

    • 크기

    • 생성 시간

    • 수정 시간

    • 접근 시간

    • 유형 (파일/디렉토리)

    • 권한

• list_allowed_directories

  • 서버가 접근할 수 있는 모든 디렉토리를 나열합니다.

  • 입력 불필요

  • 반환:

    • 이 서버가 읽고 쓸 수 있는 디렉토리

도구 어노테이션 (MCP 힌트)

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

• 읽기 전용 도구와 쓰기 가능 도구를 구분합니다.

• 어떤 쓰기 작업이 멱등적(동일한 인수로 재시도해도 안전)인지 이해합니다.

• 파괴적(데이터 덮어쓰기 또는 대규모 변경)일 수 있는 작업을 강조합니다.

• 도구가 열린 또는 외부 세계에 도달하지 않음을 알립니다 (모든 파일 시스템 도구는 openWorldHint: false를 설정합니다).

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

참고: idempotentHint와 destructiveHint는 MCP 사양에 정의된 대로 readOnlyHint가 false인 경우에만 의미가 있습니다. 모든 도구는 openWorldHint: 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}"
      ]
    }
  }
}

빌드

Docker 빌드:

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

라이선스

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 이는 MIT 라이선스의 이용 약관에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있음을 의미합니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.