MCP 파일 시스템 서버

:북마크: 정보

MCP 파일 시스템 서버는 모델 컨텍스트 프로토콜을 통해 AI 모델에 안전한 파일 시스템 액세스를 제공합니다. 엄격한 경로 검증을 시행하고 미리 정의된 디렉터리에만 액세스를 허용합니다.

:컴퓨터: 기술

:렌치: 도구

:패키지: 설치

:heavy_check_mark: 필수 조건

다음 소프트웨어를 설치해야 합니다.

노드.js (>=18.0.0)
깃
pnpm (>=8.0.0)
Docker (선택 사항)
Docker Compose (선택 사항)

:arrow_down: 저장소 복제

지엑스피1

:arrow_forward: 애플리케이션 실행

지역 개발

  # Install dependencies
  $ pnpm install

  # Build the application
  $ pnpm build

  # Run the server (specify directory to allow access to)
  $ pnpm start /path/to/allowed/directory

  # Or use configuration file
  $ pnpm start --config=config.json

NPM 패키지 사용

  # Install globally
  $ npm install -g @gabrielmaialva33/mcp-filesystem

  # Run the server
  $ mcp-filesystem /path/to/allowed/directory

  # Or use with npx (no installation needed)
  $ npx @gabrielmaialva33/mcp-filesystem /path/to/allowed/directory

  # Create a sample configuration file
  $ npx @gabrielmaialva33/mcp-filesystem --create-config=config.json

Docker 사용

  # Build the Docker image
  $ docker build -t gabrielmaialva33/mcp-filesystem .

  # Run using Docker
  $ docker run -i --rm -v /path/to/data:/data:ro gabrielmaialva33/mcp-filesystem /data

  # Use with config file
  $ docker run -i --rm -v /path/to/config.json:/app/config.json -v /path/to/data:/data gabrielmaialva33/mcp-filesystem --config=/app/config.json

Docker Compose 사용

  # Create a data directory
  $ mkdir -p data

  # Start the server
  $ docker-compose up -d

:gear: 사용법

Claude Desktop과 함께 사용

Claude Desktop은 파일 시스템 접근을 위해 이 MCP 서버를 사용하도록 구성할 수 있습니다. claude_desktop_config.json 파일에 다음을 추가하세요.

로컬 설치 사용(권장)

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-filesystem",
      "args": [
        "/Users/gabrielmaia/Documents",
        "/Users/gabrielmaia/Desktop",
        "/Users/gabrielmaia/Downloads"
      ]
    }
  }
}

실행 파일을 전역적으로 사용할 수 있도록 하세요.

# Make the binary executable
chmod +x /Users/gabrielmaia/.nvm/versions/node/v22.14.0/bin/mcp-filesystem

NPX 사용하기

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

Docker 사용

참고: Docker를 사용할 때 모든 디렉터리는 기본적으로 /projects 에 마운트되어야 합니다. ro 플래그를 추가하면 디렉터리가 읽기 전용으로 설정됩니다.

{
  "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",
        "gabrielmaialva33/mcp-filesystem",
        "/projects"
      ]
    }
  }
}

사용 가능한 도구

MCP 파일 시스템 서버는 다음과 같은 도구를 제공합니다.

파일 시스템 작업

read_file : 파일의 내용을 읽습니다.
read_multiple_files : 여러 파일을 한 번에 읽습니다.
write_file : 파일을 생성하거나 덮어씁니다.
edit_file : diff 미리보기로 정확한 편집을 수행합니다.
create_directory : 재귀적으로 디렉토리를 생성합니다
list_directory : 디렉토리 내용 나열
directory_tree : 재귀적 트리 뷰를 가져옵니다
move_file : 파일을 이동하거나 이름을 바꿉니다.
search_files : 패턴과 일치하는 파일 찾기
get_file_info : 파일 메타데이터 가져오기
list_allowed_directories : 접근 가능한 디렉토리를 확인하세요

시스템 및 네트워크 운영

get_metrics : 서버 성능 지표 보기(v0.3.0+)
execute_command : 시스템 명령을 안전하게 실행합니다(v0.3.1+)
curl_request : 외부 API에 대한 HTTP 요청 실행(v1.2.0에서 제공)

curl_request 도구 사용(v1.2.0에서 제공)

curl_request 도구를 사용하면 외부 API에 HTTP 요청을 할 수 있습니다.

// Example: Making a GET request with authentication
curl_request({
  url: 'https://api.example.com/data',
  method: 'GET',
  headers: {
    Authorization: 'Bearer your_token_here',
  },
})

// Example: POST request with JSON data
curl_request({
  url: 'https://api.example.com/create',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  data: '{"name":"Example","value":123}',
})

더 자세한 예제는 docs/curl-tool-examples.md 파일을 참조하세요.

:sparkles: 특징

핵심 기능

보안 액세스 : 엄격한 경로 검증을 통해 무단 액세스를 방지합니다.
파일 작업 : 파일 읽기, 쓰기, 편집 및 이동
디렉토리 작업 : 디렉토리 생성, 나열, 트리 뷰 가져오기 및 검색
메타데이터 액세스 : 파일 및 디렉터리 정보 보기
명령 실행 : 엄격한 검증을 통해 시스템 명령을 안전하게 실행합니다.
Docker 지원 : Docker 및 Docker Compose를 통한 간편한 배포

v0.3.0의 새로운 기능

구조화된 로깅 : 다양한 수준(디버그, 정보, 경고, 오류)의 자세한 로깅
성능 측정 항목 : 작업 횟수, 오류 및 실행 시간 추적
구성 관리 : JSON 구성 파일 지원
경로 캐싱 : 자주 액세스되는 경로의 성능 향상
개선된 오류 처리 : 구조화된 정보를 포함하는 특수 오류 유형
파일 크기 검증 : 너무 큰 파일 로딩 방지
CLI 개선 사항 : 도움말 명령, 버전 정보 및 구성 생성

구성 옵션

다음을 사용하여 구성 파일을 만들 수 있습니다.

$ mcp-filesystem --create-config=config.json

구성 예:

{
  "allowedDirectories": ["/path/to/allowed/dir1", "/path/to/allowed/dir2"],
  "logLevel": "info",
  "logFile": "/path/to/logs/mcp-filesystem.log",
  "serverName": "secure-filesystem-server",
  "serverVersion": "0.3.0",
  "cache": {
    "enabled": true,
    "maxSize": 1000,
    "ttlMs": 60000
  },
  "metrics": {
    "enabled": true,
    "reportIntervalMs": 60000
  },
  "security": {
    "maxFileSize": 10485760,
    "allowSymlinks": true,
    "validateRealPath": true
  }
}

:writing_hand: 저자


가브리엘 마이아

특허

MIT 라이센스

MCP Filesystem Server

Integrations

:북마크: 정보

:컴퓨터: 기술

:렌치: 도구

:패키지: 설치

:heavy_check_mark: 필수 조건

:arrow_down: 저장소 복제

:arrow_forward: 애플리케이션 실행

지역 개발

NPM 패키지 사용

Docker 사용

Docker Compose 사용

:gear: 사용법

Claude Desktop과 함께 사용

로컬 설치 사용(권장)

NPX 사용하기

Docker 사용

사용 가능한 도구

파일 시스템 작업

시스템 및 네트워크 운영

curl_request 도구 사용(v1.2.0에서 제공)

:sparkles: 특징

핵심 기능

v0.3.0의 새로운 기능

구성 옵션

:writing_hand: 저자

특허