파일 시스템 MCP 서버
FastMCP 기반으로 구축된 강력한 파일 시스템 관리 서버로, 파일 및 디렉터리 작업을 위한 포괄적인 도구 세트를 제공합니다. 이 서버를 사용하면 구조화된 API를 통해 다양한 파일 시스템 작업을 수행할 수 있으므로 자동화 및 다른 시스템과의 통합에 이상적입니다.
플랫폼 지원
이 서버는 다양한 운영 체제에서 작동하도록 설계되었지만 기능 수준은 다양합니다.
윈도우
- 모든 기능 지원
- 드라이브 목록
- 특수 폴더 액세스
- Windows 특정 경로 처리
- 자세한 시스템 정보
맥OS/리눅스
- 기본 파일 작업
- 디렉토리 작업
- 파일 검색 및 메타데이터
- 기본 시스템 정보
- 참고: 일부 Windows 특정 기능은 사용할 수 없습니다.
향후 구현
계획된 macOS 지원
- macOS용 기본 경로 처리
- macOS 특정 시스템 정보 검색
- macOS 파일 시스템 기능과의 통합
- macOS 특정 파일 속성 지원
- macOS 전용 유틸리티 구현(windows_utils.py와 유사)
계획된 Linux 지원
- Linux용 기본 경로 처리
- Linux 특정 시스템 정보 검색
- Linux 파일 시스템 기능과의 통합
- Linux 파일 권한 및 속성 지원
- Linux 전용 유틸리티 구현
크로스 플랫폼 개선
- 통합 경로 처리 시스템
- 플랫폼에 구애받지 않는 드라이브 감지
- 일관된 시스템 정보 API
- 플랫폼 간 표준화된 파일 속성
- 크로스 플랫폼 파일 시스템 이벤트 모니터링
- 범용 파일 수집 시스템
타임라인
- 1단계: 기본 크로스 플랫폼 호환성 개선
- 2단계: 플랫폼별 기능 구현
- 3단계: 고급 크로스 플랫폼 기능
- 4단계: 성능 최적화 및 개선
특징
파일 작업
- 백업 지원으로 파일 복사
- 백업 지원을 통한 파일 이동
- 안전 검사가 적용된 파일 삭제
- 파일 내용 읽기
- 파일 내용 쓰기
- 파일 정보(크기, 생성 시간, 수정 시간) 가져오기
- 이름 패턴으로 파일 검색
- 관련 파일을 정리하기 위한 파일 컬렉션을 만듭니다.
디렉토리 작업
- 디렉토리 내용 나열
- 디렉토리 생성
- 디렉토리 삭제
- 디렉토리를 재귀적으로 나열합니다(트리와 같은 구조)
- 이름 패턴으로 디렉토리 검색
시스템 정보
- 시스템 정보(OS, CPU, 메모리, 디스크 사용량)를 가져옵니다.
- 디스크 정보 가져오기(전체 공간, 사용된 공간, 여유 공간)
- 디렉토리 정보 가져오기(파일 수, 총 크기)
프로젝트 구조
지엑스피1
컬렉션 스토리지
컬렉션은 사용자가 지정한 모든 디렉터리에 저장할 수 있습니다. 저장 위치를 지정하지 않으면 프로젝트의 data/collections 디렉터리 내 기본 위치에 저장됩니다.
사용 예:
# Store in default location
create_collection("my_collection", ["file1.txt", "file2.txt"])
# Store in custom location
create_collection("my_collection", ["file1.txt", "file2.txt"], storage_path="/path/to/store")
종속성
필수 종속성
- 패스트MCP
- 피단틱
- pywin32(Windows 전용)
- WMI(Windows 전용)
종속성을 설치하려면:
pip install -r requirements.txt
설정
- 저장소를 복제합니다.
git clone https://github.com/calebmwelsh/file-system-mcp-server.git
cd file-system-mcp-server
- 가상 환경을 만들고 활성화하세요.
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- 종속성 설치:
pip install -r requirements.txt
용법
다양한 개발 환경(Claude, Cursor, Windsurf)에 대한 자세한 MCP 구성 지침은 MCP 구성 가이드를 참조하세요.
Claude와의 통합
Claude와 파일 시스템 MCP 서버를 통합하려면 claude_desktop_config.json 파일에 다음을 추가하세요.
{
"mcpServers": {
"file-system": {
"command": "/absolute/path/to/python",
"args": [
"/absolute/path/to/file-system-mcp-server/fs_server.py"
]
}
}
}
파이썬 경로 찾기
Python 실행 파일 경로를 찾으려면 다음 명령을 사용하세요.
윈도우(PowerShell):
(Get-Command python).Source
Windows(명령 프롬프트/터미널):
Linux/macOS(터미널):
/absolute/path/to/python 위의 해당 명령의 출력으로 바꾸세요.
구성 예
Windows의 경우 구성은 다음과 같습니다.
{
"mcpServers": {
"file-system": {
"command": "C:\\Users\\YourUsername\\AppData\\Local\\Programs\\Python\\Python39\\python.exe",
"args": [
"C:\\Users\\YourUsername\\Documents/file-system-mcp-server/fs_server.py"
]
}
}
}
macOS/Linux의 경우:
{
"mcpServers": {
"file-system": {
"command": "/usr/local/bin/python3",
"args": [
"/Users/YourUsername/Documents/file-system-mcp-server/fs_server.py"
]
}
}
}
구성을 추가한 후:
claude_desktop_config.json 파일을 저장합니다.- 클로드를 다시 시작하세요
- 이제 Claude에게 파일 작업을 수행하도록 요청하여 파일 시스템 도구를 사용할 수 있습니다.
사용 가능한 도구
파일 작업
copy_file : 선택적 백업을 포함한 파일 복사move_file : 선택적 백업으로 파일 이동delete_file : 안전 검사를 통해 파일을 삭제합니다.read_file : 파일 내용 읽기write_file : 파일에 내용을 씁니다.get_file_info : 자세한 파일 정보를 가져옵니다search_files : 이름 패턴으로 파일 검색create_collection : 파일 컬렉션을 생성합니다.
디렉토리 작업
list_directory : 디렉토리 내용 나열create_directory : 새로운 디렉토리를 생성합니다delete_directory : 디렉토리 삭제list_directory_recursively : 디렉토리 구조를 트리 형식으로 표시합니다.search_directories : 이름 패턴으로 디렉토리 검색
시스템 정보
get_system_info : 시스템 정보 가져오기get_disk_info : 디스크 사용 정보 가져오기get_directory_info : 디렉토리 통계 가져오기
알려진 문제
다음 기능은 현재 문제가 발생하여 예상대로 작동하지 않을 수 있습니다.
- 파일 삭제 기능
delete_file 함수는 어떤 경우에는 파일을 제대로 삭제하지 못할 수 있습니다.- 사용자는 파일 삭제를 수동으로 확인하거나 중요한 경우 대체 방법을 사용하는 것이 좋습니다.
- 문제는 조사 중이며 향후 업데이트에서 수정될 예정입니다.
- 드라이브 목록 기능
list_drives 함수는 사용 가능한 모든 드라이브를 올바르게 감지하거나 표시하지 못할 수 있습니다.- 일부 드라이브가 목록에서 누락되었거나 잘못된 정보가 표시될 수 있습니다.
- 이는 알려진 제한 사항이며 향후 업데이트에서 해결될 예정입니다.
- 플랫폼별 제한 사항
- Windows 전용 기능은 macOS/Linux에서는 사용할 수 없습니다.
- 일부 경로 처리 방식은 플랫폼마다 다를 수 있습니다.
- 시스템 정보 검색은 플랫폼마다 다릅니다.
오류 처리
서버에는 다음에 대한 포괄적인 오류 처리 기능이 포함되어 있습니다.
- 잘못된 파일 경로
- 파일/디렉토리를 찾을 수 없습니다
- 권한 문제
- 디스크 공간 제한
- 잘못된 작업
- 플랫폼별 오류
보안
- 모든 파일 작업에는 경로 검증이 포함됩니다.
- 파괴적인 작업 전에 백업 파일이 생성됩니다.
- 시스템 정보 접근은 안전한 운영을 위해 제한됩니다.
- 파일 작업은 적절한 오류 처리를 통해 수행됩니다.
기여하다
- 저장소를 포크하세요
- 기능 브랜치 생성
- 변경 사항을 커밋하세요
- 지점으로 밀어 넣기
- 풀 리퀘스트 만들기
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.
감사의 말
- FastMCP로 구축됨
- 데이터 검증을 위해 Pydantic을 사용합니다.
- 최신 파일 시스템 관리 도구에서 영감을 받음