파일 시스템 MCP 서버

포괄적인 권한 제어와 향상된 기능을 갖춘 파일 시스템 작업을 위한 모델 컨텍스트 프로토콜(MCP)을 구현하는 Node.js 서버입니다.

특징

세분화된 권한 제어(읽기 전용, 전체 액세스 또는 특정 작업 권한)
허용된 디렉토리 내에서 보안 파일 작업
파일 작업:
- 파일 읽기/쓰기/수정
- 디렉토리 생성/나열/삭제
- 파일/디렉토리 이동
- 이름이나 확장자로 파일 검색
- 파일 메타데이터 가져오기
디렉토리 작업:
- 디렉토리 구조의 트리 뷰
- 제외 패턴을 사용한 재귀 연산
유틸리티 기능:
- XML에서 JSON으로 변환
- 한 번의 호출로 여러 파일 작업 수행
- 패턴 매칭을 통한 고급 파일 편집
보안 기능:
- 심볼릭 링크 제어
- 경로 검증
- 샌드박스 운영

참고 : 서버는 args 통해 지정된 디렉토리 내에서만 작업을 허용하고 구성된 권한에 따라 작업을 수행합니다.

API

자원

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

도구

읽기_파일
- 파일의 전체 내용 읽기
- 입력: path (문자열)
- UTF-8 인코딩으로 전체 파일 내용을 읽습니다.
여러 파일 읽기
- 여러 파일을 동시에 읽기
- 입력: paths (문자열[])
- 읽기에 실패해도 전체 작업이 중단되지는 않습니다.
파일 생성
- 콘텐츠가 있는 새 파일을 만듭니다.
- 입력:
  - path (문자열): 파일 위치
  - content (문자열): 파일 내용
- 파일이 이미 존재하면 실패합니다.
- create 권한이 필요합니다
수정_파일
- 기존 파일을 새 콘텐츠로 수정
- 입력:
  - path (문자열): 파일 위치
  - content (문자열): 새 파일 내용
- 파일이 존재하지 않으면 실패합니다.
- edit 권한이 필요합니다
편집_파일
- 패턴 매칭 및 서식을 사용하여 선택적 편집을 수행합니다.
- 특징:
  - 줄 기반 및 다중 줄 콘텐츠 매칭
  - 들여쓰기 보존을 통한 공백 정규화
  - 올바른 위치 지정을 통한 여러 동시 편집
  - 들여쓰기 스타일 감지 및 보존
  - 컨텍스트가 포함된 Git 스타일 diff 출력
  - 드라이런 모드로 변경 사항 미리 보기
- 입력:
  - path (문자열): 편집할 파일
  - edits (배열): 편집 작업 목록
    - oldText (문자열): 검색할 텍스트(정확히 일치)
    - newText (문자열): 바꿀 텍스트
  - dryRun (부울): 변경 사항을 적용하지 않고 미리 봅니다(기본값: false)
- 드라이런에 대한 자세한 diff를 반환하고, 그렇지 않으면 변경 사항을 적용합니다.
- edit 권한이 필요합니다
- 모범 사례: 항상 dryRun을 먼저 사용하여 변경 사항을 미리 봅니다.
디렉토리 생성
- 새 디렉토리를 생성하거나 디렉토리가 존재하는지 확인하세요.
- 입력: path (문자열)
- 필요한 경우 상위 디렉토리를 생성합니다.
- 디렉토리가 있으면 자동으로 성공합니다.
- create 권한이 필요합니다
목록_디렉토리
- [FILE] 또는 [DIR] 접두사를 사용하여 디렉토리 내용을 나열합니다.
- 입력: path (문자열)
- 파일 및 디렉토리의 자세한 목록을 반환합니다.
디렉토리 트리
- 디렉토리 구조의 재귀적 트리 뷰 가져오기
- 입력: path (문자열)
- 파일 및 디렉토리가 포함된 JSON 구조를 반환합니다.
- 각 항목에는 이름, 유형 및 자식(디렉토리용)이 포함됩니다.
이동_파일
- 파일 및 디렉토리 이동 또는 이름 변경
- 입력:
  - source (문자열): 소스 경로
  - destination (문자열): 목적지 경로
- 대상이 존재하면 실패합니다.
- 파일과 디렉토리 모두에 적용 가능
- move 허가가 필요합니다
파일 삭제
- 파일 삭제
- 입력: path (문자열)
- 파일이 존재하지 않으면 실패합니다.
- delete 권한이 필요합니다
디렉토리 삭제
- 디렉토리 삭제
- 입력:
  - path (문자열): 삭제할 디렉토리
  - recursive (boolean): 내용을 삭제할지 여부(기본값: false)
- 디렉토리가 비어 있지 않고 recursive가 false이면 실패합니다.
- delete 권한이 필요합니다
검색_파일
- 재귀적으로 파일/디렉토리 검색
- 입력:
  - path (문자열): 시작 디렉토리
  - pattern (문자열): 패턴 검색
  - excludePatterns (string[]): 패턴 제외(glob 형식 지원)
- 대소문자 구분 없이 일치
- 일치 항목의 전체 경로를 반환합니다.
확장자로 파일 찾기
- 특정 확장자를 가진 모든 파일 찾기
- 입력:
  - path (문자열): 시작 디렉토리
  - extension (문자열): 찾을 파일 확장자
  - excludePatterns (문자열[]): 선택적 제외 패턴
- 대소문자 구분 없이 확장자 매칭
- 일치하는 파일의 전체 경로를 반환합니다.
파일_정보_받기
- 자세한 파일/디렉토리 메타데이터 가져오기
- 입력: path (문자열)
- 보고:
  - 크기
  - 창조 시간
  - 수정된 시간
  - 접속 시간
  - 유형(파일/디렉토리)
  - 권한
권한 얻기
- 현재 서버 권한 가져오기
- 입력이 필요하지 않습니다
- 보고:
  - 권한 플래그(읽기 전용, 전체 액세스, 생성, 편집, 이동, 삭제)
  - 심볼릭 링크 팔로우 상태
  - 허용된 디렉토리 수
허용된 디렉토리 목록
- 서버가 액세스할 수 있는 모든 디렉토리를 나열합니다.
- 입력이 필요하지 않습니다
- 허용된 디렉토리 경로 배열을 반환합니다.
xml_to_json
- XML 파일을 JSON 형식으로 변환
- 입력:
  - xmlPath (문자열): 소스 XML 파일
  - jsonPath (문자열): 대상 JSON 파일
  - options (객체): 선택 설정
    - ignoreAttributes (부울): XML 속성 건너뛰기(기본값: false)
    - preserveOrder (부울): 속성 순서 유지(기본값: true)
    - format (boolean): JSON을 예쁘게 인쇄합니다(기본값: true)
    - indentSize (숫자): JSON 들여쓰기(기본값: 2)
- XML 파일에 대한 read 권한이 필요합니다.
- JSON 파일에 대한 create 또는 edit 권한이 필요합니다.
xml_to_json_string
- XML 파일을 JSON 문자열로 변환
- 입력:
  - xmlPath (문자열): 소스 XML 파일
  - options (객체): 선택 설정
    - ignoreAttributes (부울): XML 속성 건너뛰기(기본값: false)
    - preserveOrder (부울): 속성 순서 유지(기본값: true)
- XML 파일에 대한 read 권한이 필요합니다.
- JSON 문자열 표현을 반환합니다.
xml_쿼리
- XPath 표현식을 사용하여 XML 파일 쿼리
- 입력:
  - path (문자열): XML 파일 경로
  - query (문자열, 선택 사항): 실행할 XPath 쿼리
  - structureOnly (boolean, 선택 사항): 태그 구조만 반환합니다.
  - maxBytes (숫자, 선택 사항): 읽을 최대 바이트(기본값: 1MB)
  - includeAttributes (부울, 선택 사항): 속성 정보 포함(기본값: true)
- XPath 예:
  - 모든 요소 가져오기: //tagname
  - 특정 속성을 가진 요소를 가져옵니다: //tagname[@attr="value"]
  - 텍스트 콘텐츠 가져오기: //tagname/text()
- 대용량 XML 파일에 대한 메모리 효율성
- 쿼리 결과 또는 구조의 JSON 표현을 반환합니다.
xml_구조
- 전체 파일을 읽지 않고 XML 구조 분석
- 입력:
  - path (문자열): XML 파일 경로
  - depth (숫자, 선택 사항): 분석 깊이(기본값: 2)
  - includeAttributes (부울, 선택 사항): 속성 분석 포함
  - maxBytes (숫자, 선택 사항): 읽을 최대 바이트(기본값: 1MB)
- 요소, 속성 및 구조에 대한 통계 정보를 반환합니다.
- 자세한 분석 전에 대용량 XML 파일을 이해하는 데 유용합니다.

권한 및 보안

서버는 세부적인 권한 제어를 통해 포괄적인 보안 모델을 구현합니다.

디렉토리 액세스 제어

작업은 args 통해 시작 중에 지정된 디렉토리로 엄격하게 제한됩니다.
모든 작업(심볼릭 링크 대상 포함)은 허용된 디렉토리 내에 있어야 합니다.
경로 검증은 허용된 경로 외부에서 디렉토리 탐색이나 액세스가 발생하지 않도록 보장합니다.

권한 플래그

--readonly : 다른 모든 권한 플래그를 무시하고 읽기 전용 모드를 적용합니다.
--full-access : 모든 작업(생성, 편집, 이동, 삭제)을 활성화합니다.
개별 권한 플래그(--full-access가 설정되지 않은 경우 명시적으로 활성화해야 함):
- --allow-create : 새로운 파일 및 디렉토리 생성을 허용합니다.
- --allow-edit : 기존 파일 수정을 허용합니다.
- --allow-move : 파일 및 디렉토리 이동/이름 변경 허용
- --allow-delete : 파일 및 디렉토리 삭제 허용

기본 동작 : 권한 플래그를 지정하지 않으면 서버는 읽기 전용 모드로 실행됩니다. 쓰기 작업을 허용하려면 --full-access 또는 특정 --allow-* 플래그를 사용해야 합니다.

심볼릭 링크 처리

기본적으로 심볼릭 링크가 따라갑니다(링크와 대상 모두 허용된 디렉토리에 있어야 함)
--no-follow-symlinks : 심볼릭 링크 팔로우를 비활성화합니다(작업은 링크 자체에서 실행됩니다).

Claude Desktop 및 커서 사용

Claude Desktop의 경우 claude_desktop_config.json 또는 Cursor의 경우 .cursor/mcp.json 에 적절한 구성을 추가합니다.

커서 구성

.cursor/mcp.json 에서:

지엑스피1

Docker 구성

Docker를 사용한 Claude Desktop의 경우:

{
  "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",
        "--readonly",                    // For read-only access
        "--no-follow-symlinks",         // Optional: prevent symlink following
        "/projects"
      ]
    }
  }
}

NPX 구성

NPX를 사용하는 Claude Desktop 또는 Cursor의 경우:

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

권한 플래그 예

다양한 권한 조합으로 서버를 구성할 수 있습니다.

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/path/to/allowed/directory",
  "--readonly"                         // Read-only mode
]

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/path/to/allowed/directory",
  "--full-access",                    // Full read/write access
  "--no-follow-symlinks"              // Don't follow symlinks
]

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/path/to/allowed/directory",
  "--allow-create",                   // Selective permissions
  "--allow-edit"                      // Only allow creation and editing
]

참고: --readonly 다른 모든 권한 플래그보다 우선하며, --full-access --readonly 지정되지 않은 경우 모든 작업을 활성화합니다.

여러 디렉터리 및 권한

여러 디렉토리를 지정하는 경우 권한 플래그는 모든 디렉토리에 전역적으로 적용됩니다.

"args": [
  "/path/to/mcp-filesystem/dist/index.js",
  "~/first/directory",                // Both directories have the same
  "~/second/directory",               // permission settings (read-only)
  "--readonly"
]

다양한 디렉토리에 대해 서로 다른 권한 수준이 필요한 경우 여러 서버 구성을 만드세요.

{
  "mcpServers": {
    "readonly-filesystem": {
      "command": "node",
      "args": [
        "/path/to/mcp-filesystem/dist/index.js",
        "~/sensitive/directory",
        "--readonly"
      ]
    },
    "writeable-filesystem": {
      "command": "node",
      "args": [
        "/path/to/mcp-filesystem/dist/index.js",
        "~/sandbox/directory",
        "--full-access"
      ]
    }
  }
}

명령줄 예제

읽기 전용 액세스:

npx -y @modelcontextprotocol/server-filesystem --readonly /path/to/dir

전체 접근:

npx -y @modelcontextprotocol/server-filesystem --full-access /path/to/dir

특정 권한:

npx -y @modelcontextprotocol/server-filesystem --allow-create --allow-edit /path/to/dir

다음에 심볼릭 링크가 없습니다.

npx -y @modelcontextprotocol/server-filesystem --full-access --no-follow-symlinks /path/to/dir

짓다

Docker 빌드:

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

특허

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

Filesystem MCP Server