WSL용 파일 시스템 MCP 서버

⚠️ 중요 정보:
원래 파일 시스템 MCP 서버는 구성에서 네트워크 경로 \\wsl.localhost\DistributionName 매개변수로 사용하여 간단히 WSL 파일에 액세스할 수 있습니다.
예:
지엑스피1
하지만 이 프로젝트는 WSL Linux 배포판에 특별히 최적화된 대체 구현을 제공합니다.
공식 서버는 Node.js의 fs 모듈을 사용하여 디렉터리를 재귀적으로 탐색하는 반면, 이 구현에서는 WSL 내부의 기본 Linux 명령 (예: find , grep 등)을 활용하여 파일 목록 작성 및 콘텐츠 검색 작업을 훨씬 빠르게 진행합니다 .
이 기능은 대규모 디렉토리 트리를 처리하거나 검색 성능이 중요할 때 특히 유용할 수 있습니다.
따라서 많은 사용 사례에서 기본 네트워크 경로가 더 간단할 수 있지만, 이 프로젝트는 더 나은 성능 이나 인덱싱 및 검색 논리에 대한 보다 사용자 지정 제어를 원하는 WSL 사용자에게는 여전히 귀중한 솔루션입니다 .

WSL용 파일 시스템 MCP 서버

Linux용 Windows 하위 시스템(WSL)에서 파일 시스템 작업을 위해 특별히 설계된 모델 컨텍스트 프로토콜(MCP)을 구현하는 Node.js 서버입니다.
이 프로젝트는 원래의 Filesystem MCP Server 에서 파생되었지만 WSL 환경에 맞춰 완전히 재구성되었습니다.
일반 파일 작업을 처리하는 원래 프로젝트와 달리 이 버전은 WSL에서 Windows와 Linux 배포판 간의 원활한 상호 작용에만 초점을 맞춥니다.
두 프로젝트는 호환되며 동일한 시스템에서 병렬로 실행할 수 있습니다.

특징

Windows에서 모든 WSL 배포에 액세스
Windows 호스트에서 WSL로 파일 읽기/쓰기
WSL에서 디렉토리 생성/나열/삭제
WSL 파일 시스템에서 파일/디렉토리 이동
WSL 내에서 파일 검색
WSL 파일 시스템에서 파일 메타데이터 가져오기
여러 WSL 배포판 지원

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

API

자원

wsl -d <distrib> : WSL 배포판에서 작업을 위한 명령

도구

읽기_파일
- WSL에서 파일의 전체 내용 읽기
- 입력: path (문자열)
- UTF-8 텍스트로 콘텐츠를 읽습니다.
여러 파일 읽기
- WSL에서 여러 파일을 동시에 읽기
- 입력: paths (문자열[])
- 읽기에 실패해도 전체 작업이 중단되지는 않습니다.
쓰기_파일
- WSL에서 파일을 생성하거나 덮어씁니다(신중하게 사용하세요)
- 입력:
  - path (문자열)
  - content (문자열)
편집_파일
- 고급 패턴 매칭 및 서식을 사용한 선택적 편집
- 입력:
  - path (문자열)
  - edits ( { oldText, newText } 의 배열)
  - dryRun (부울, 선택 사항)
- 특징:
  - 다중 라인 매칭
  - 들여쓰기 보존
  - Git 스타일 diff 미리보기
  - 비파괴 드라이런 모드
디렉토리 생성
- WSL에서 디렉토리를 생성하거나 존재 여부를 확인합니다.
- 입력: path (문자열)
목록_디렉토리
- [FILE] 또는 [DIR] 접두사를 사용하여 디렉토리 내용을 나열합니다.
- 입력: path (문자열)
디렉토리 트리
- 콘텐츠의 재귀적 JSON 트리 뷰
- 입력: path (문자열)
이동_파일
- 파일/디렉토리 이동 또는 이름 변경
- 입력:
  - source (문자열)
  - destination (문자열)
검색_파일
- 이름으로 재귀적으로 검색
- 입력:
  - path (문자열)
  - pattern (문자열)
  - excludePatterns (문자열[], 선택 사항)
파일_정보_받기
- 자세한 메타데이터
- 입력: path (문자열)
- 반환: 크기, 타임스탬프, 유형, 권한
허용된 디렉토리 목록
- 서버에서 접근 가능한 모든 디렉토리를 나열합니다.
list_wsl_distributions
- 사용 가능한 배포판을 나열하고 활성 배포판을 표시합니다.

요구 사항

Linux용 Windows 하위 시스템(WSL)이 올바르게 구성됨
WSL에 하나 이상의 Linux 배포판이 설치됨

Claude Desktop 사용자의 경우:
추가 설치는 필요 없습니다. claude_desktop_config.json 구성하기만 하면 됩니다.

개발을 위해:

Node.js (v14.0.0 이상)
TypeScript(개발 종속성으로 포함됨)

Windows에 Node.js 설치

nodejs.org 에서 설치 프로그램을 다운로드하세요
실행하고 지침을 따르세요
버전 확인:

node --version
npm --version

용법

서버를 실행하기 전에 TypeScript 프로젝트를 빌드해야 합니다.

npm install
npm run build

사용할 WSL 배포판(선택 사항)과 노출할 디렉토리를 지정하여 서버를 실행합니다.

node dist/index.js [--distro=distribution_name] <allowed_directory> [additional_directories...]

배포판을 지정하지 않으면 기본 WSL 배포판이 사용됩니다.

예시

Ubuntu-20.04 배포판에 접속하세요:

node dist/index.js --distro=Ubuntu-20.04 /home/user/documents

기본 배포 사용:

node dist/index.js /home/user/documents

Claude Desktop과 함께 사용

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

옵션 1: 특정 WSL 배포판 사용

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "--distro=Ubuntu-20.04",
        "/home/user/documents"
      ]
    }
  }
}

옵션 2: 기본 WSL 배포 사용

{
  "mcpServers": {
    "wsl-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-wsl-filesystem",
        "/home/user/documents"
      ]
    }
  }
}

두 번째 예에서는 사용자가 WSL 배포판을 지정하지 않아도 시스템이 기본 WSL 배포판을 사용합니다.

원래 프로젝트와의 차이점

이 포크는 다음과 같은 방법으로 원래 파일 시스템 MCP 서버를 WSL과 함께 작동하도록 조정합니다.

직접 Node.js 파일 시스템 호출을 WSL 명령 실행으로 대체
특정 WSL 배포판 선택에 대한 지원 추가
Windows와 Linux 형식 간 경로 변환 구현
플랫폼 간 호환성을 위한 파일 콘텐츠 처리 향상
WSL 관리를 위한 전문 도구 추가

특허

이 프로젝트는 Model Context Protocol 팀이 만든 원래 Filesystem MCP Server 의 포크입니다.

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

Filesystem MCP Server for WSL

Integrations