파일 시스템 MCP 서버

견고하고 플랫폼에 독립적인 파일 시스템 기능으로 AI 에이전트의 역량을 강화하세요.

이 모델 컨텍스트 프로토콜(MCP) 서버는 AI 에이전트가 로컬 파일 시스템과 상호 작용할 수 있는 안전하고 안정적인 인터페이스를 제공합니다. 포괄적인 로깅, 오류 처리 및 보안 기능을 갖춘 프로덕션용 TypeScript 기반을 기반으로 파일 및 디렉터리를 읽고, 쓰고, 업데이트하고, 관리할 수 있습니다.

개요

모델 컨텍스트 프로토콜(MCP)은 AI 모델이 외부 도구 및 데이터 소스(리소스)와 안전하게 상호 작용할 수 있도록 하는 표준 프레임워크입니다. 이 서버는 MCP 표준을 구현하여 필수 파일 시스템 작업을 도구로 제공하여 AI 에이전트가 다음과 같은 작업을 수행할 수 있도록 합니다.

파일 내용을 읽고 분석합니다.
파일을 생성, 수정 또는 덮어씁니다.
디렉토리와 파일 경로를 관리합니다.
파일 내에서 타겟형 업데이트를 수행합니다.

TypeScript로 구축된 이 서버는 유형 안전성, 모듈성, 견고한 오류 처리를 강조하므로 AI 워크플로에 안정적으로 통합하는 데 적합합니다.

건축학

서버는 명확성과 유지관리성을 위해 계층화된 아키텍처를 채택했습니다.

지엑스피1

API 계층 : MCP 통신을 처리하고 Zod를 사용하여 입력을 검증하고 경로를 정리합니다.
핵심 서비스 : 구성, 로깅, 오류 보고, 세션 상태(기본 작업 디렉토리와 같음) 및 기본 MCP 서버 인스턴스를 관리합니다.
도구 구현 : 공유 유틸리티를 활용하여 각 파일 시스템 도구에 대한 특정 논리를 포함합니다.

특징

포괄적인 파일 작업 : 파일 및 디렉토리를 읽고, 쓰고, 나열하고, 삭제하고, 이동하고, 복사하기 위한 도구입니다.
타겟 업데이트 : update_file 도구는 일반 텍스트와 정규식을 지원하여 파일 내에서 정확한 검색 및 교체 작업을 수행할 수 있습니다.
세션 인식 경로 관리 : set_filesystem_default 도구는 세션 동안 상대 경로를 확인하기 위한 기본 작업 디렉터리를 설정합니다.
보안 우선 : 내장된 경로 정리 기능으로 디렉터리 트래버설 공격을 방지합니다. 선택적인 기본 디렉터리 제한 기능으로 보안을 강화합니다.
견고한 기초 : 다음을 위한 생산 등급 유틸리티가 포함되어 있습니다.
- 구조화된 상황 인식 로깅.
- 특정 오류 코드를 사용한 표준화된 오류 처리.
- 요청 추적을 위한 고유 ID 생성.
- 입력 정리.
- 선택적 속도 제한(util 파일이 생성되었지만 아직 통합되지 않음).
타입 안전성 : TypeScript로 완벽하게 구현되어 안정성과 유지 관리성이 향상되었습니다.

설치

단계

저장소를 복제합니다.
git clone https://github.com/cyanheads/filesystem-mcp-server.git cd filesystem-mcp-server
종속성 설치:
npm install
프로젝트를 빌드하세요:
npm run build
이렇게 하면 TypeScript 코드가 dist/ 디렉터리의 JavaScript로 컴파일되고, 메인 스크립트가 실행 가능하게 됩니다. 실행 파일은 dist/index.js 에 저장됩니다.

구성

환경 변수를 사용하여 서버를 구성합니다.

FS_BASE_DIRECTORY (선택 사항, 보안을 위해 권장 ):
- 절대 경로로 설정하면 서버에서 수행하는 모든 파일 작업이 해당 디렉터리와 그 하위 디렉터리로 엄격하게 제한됩니다. 이를 통해 AI 에이전트가 의도한 범위를 벗어난 파일에 액세스하는 것을 방지할 수 있습니다.
- 예: FS_BASE_DIRECTORY=/Users/casey/safe-agent-files
LOG_LEVEL (선택 사항):
- 로그의 자세한 정도를 제어합니다. 옵션: error , warn , info , http , verbose , debug , silly .
- 기본값은 info 입니다.
LOG_DIR (선택 사항):
- 로그 파일( combined.log , error.log )이 저장될 디렉토리를 지정합니다.
- 서버의 실행 디렉토리를 기준으로 ./logs 가 기본값입니다.

MCP 클라이언트와 함께 사용

MCP 클라이언트(AI 어시스턴트 등)가 이 서버를 사용하도록 허용하려면 다음을 수행합니다.

서버 실행: 터미널에서 서버를 시작합니다.
node dist/index.js # Or if you are in the project root: # npm start
클라이언트 구성: MCP 클라이언트 구성에 서버를 추가합니다. 정확한 방법은 클라이언트에 따라 다르지만 일반적으로 다음을 지정합니다.
- 명령어: node
- 인수: 빌드된 서버 실행 파일의 절대 경로(예: /path/to/filesystem-mcp-server/dist/index.js ).
- 환경 변수(선택 사항): 필요에 따라 FS_BASE_DIRECTORY , LOG_LEVEL 또는 LOG_DIR 설정합니다.
MCP 설정 예시(개념적):
{ "mcpServers": { "filesystem": { "command": "node", "args": ["/path/to/filesystem-mcp-server/dist/index.js"], "env": { "FS_BASE_DIRECTORY": "/path/to/base/directory", "LOG_LEVEL": "debug" }, "disabled": false, "autoApprove": [] } // ... other servers } }

구성하고 실행하면 클라이언트가 서버와 사용 가능한 도구를 감지합니다.

사용 가능한 도구

서버는 파일 시스템과의 상호작용을 위해 다음과 같은 도구를 제공합니다.

도구	설명
`set_filesystem_default`	현재 세션의 기본 절대 경로를 설정합니다. 이후 도구 호출에 사용되는 상대 경로는 이 기본값을 기준으로 확인됩니다. 서버 재시작 시 재설정됩니다.
`read_file`	지정된 파일의 전체 내용을 UTF-8 텍스트로 읽습니다. 상대 경로(기본값으로 확인됨) 또는 절대 경로를 사용할 수 있습니다.
`write_file`	지정된 파일에 내용을 씁니다. 파일이 없으면 파일(및 필요한 상위 디렉터리)을 생성하고, 파일이 있으면 덮어씁니다. 상대 경로 또는 절대 경로를 사용할 수 있습니다.
`update_file`	`{search, replace}` 블록 배열을 사용하여 기존 파일 내에서 특정 대상 검색 및 바꾸기 작업을 수행합니다. 지역화된 변경 사항에 적합합니다. 일반 텍스트 또는 정규 표현식 검색( `useRegex: true` )과 모든 항목 바꾸기( `replaceAll: true` )를 지원합니다. 상대 경로 또는 절대 경로를 사용할 수 있습니다. 파일이 존재해야 합니다.
`list_files`	지정된 경로 내의 파일과 디렉터리를 나열합니다. 재귀적 나열( `includeNested: true` ) 및 항목 수 제한( `maxEntries` ) 등의 옵션이 있습니다. 형식이 지정된 트리 구조를 반환합니다. 상대 또는 절대 경로를 사용할 수 있습니다.
`delete_file`	특정 파일을 영구적으로 제거합니다. 상대 경로 또는 절대 경로를 사용할 수 있습니다.
`delete_directory`	디렉터리를 영구적으로 제거합니다. 비어 있지 않은 디렉터리와 그 내용을 제거하려면 `recursive: true` 사용하세요(주의해서 사용하세요!). 상대 경로 또는 절대 경로를 사용할 수 있습니다.
`create_directory`	지정된 경로에 새 디렉터리를 생성합니다. 기본적으로( `create_parents: true` ) 필요한 상위 디렉터리도 생성합니다. 상대 경로 또는 절대 경로를 사용할 수 있습니다.
`move_path`	파일이나 디렉터리를 원본 경로에서 대상 경로로 이동하거나 이름을 바꿉니다. 상대 경로와 절대 경로를 모두 사용할 수 있습니다.
`copy_path`	원본 경로에서 대상 경로로 파일이나 디렉터리를 복사합니다. 디렉터리의 경우 기본적으로 재귀적으로 복사합니다( `recursive: true` ). 상대 경로 또는 절대 경로를 사용할 수 있습니다.

자세한 입력/출력 스키마(Zod/JSON 스키마)는 도구 등록 파일( src/mcp-server/tools/*/registration.ts )을 참조하세요.

프로젝트 구조

코드베이스는 명확성과 유지 관리를 위해 구성되어 있습니다.

filesystem-mcp-server/
├── dist/                 # Compiled JavaScript output (after npm run build)
├── logs/                 # Log files (created at runtime)
├── node_modules/         # Project dependencies
├── src/                  # TypeScript source code
│   ├── config/           # Configuration loading (index.ts)
│   ├── mcp-server/       # Core MCP server logic
│   │   ├── server.ts     # Server initialization and tool registration
│   │   ├── state.ts      # Session state management (e.g., default path)
│   │   └── tools/        # Individual tool implementations (one subdir per tool)
│   │       ├── readFile/
│   │       │   ├── index.ts
│   │       │   ├── readFileLogic.ts
│   │       │   └── registration.ts
│   │       └── ...       # Other tools (writeFile, updateFile, etc.)
│   ├── types-global/     # Shared TypeScript types and interfaces
│   │   ├── errors.ts     # Custom error classes and codes
│   │   ├── mcp.ts        # MCP related types
│   │   └── tool.ts       # Tool definition types
│   ├── utils/            # Reusable utility modules
│   │   ├── errorHandler.ts
│   │   ├── idGenerator.ts
│   │   ├── index.ts
│   │   ├── logger.ts
│   │   ├── rateLimiter.ts
│   │   ├── requestContext.ts
│   │   └── sanitization.ts
│   └── index.ts          # Main application entry point
├── .clinerules           # Cheatsheet for LLM assistants
├── .gitignore
├── LICENSE
├── package.json
├── package-lock.json
├── README.md             # This file
└── tsconfig.json         # TypeScript compiler options

현재 구조의 라이브 상세 보기를 보려면 npm run tree 실행하세요.

개발자 참고: 이 저장소에는 .clinerules 파일이 포함되어 있습니다. 이 치트 시트는 LLM 코딩 어시스턴트에게 코드베이스 패턴, 파일 위치 및 사용 예에 대한 필수 정보를 제공합니다. 서버가 업데이트될 때마다 업데이트해 주세요!

특허

이 프로젝트는 Apache 라이선스 2.0에 따라 라이선스가 부여됩니다. 자세한 내용은 라이선스 파일을 참조하세요.

Filesystem MCP Server

Integrations