mcp-filesystem

강화된 파일시스템 MCP 서버입니다. 선택한 디렉터리 집합에 대해 로컬 모델에게 읽기 및 쓰기 접근 권한을 부여하며, 그 외에는 아무것도 허용하지 않습니다.

MCP TypeScript SDK v2를 기반으로 2026-07-28 프로토콜 리비전에 맞춰 제작되었으며, 동일한 엔드포인트에서 2025년경 클라이언트와 하위 호환됩니다. stdio(LM Studio, Claude Desktop 및 로컬 프로세스를 생성하는 기타 모든 환경용) 또는 Streamable HTTP(컨테이너화된 공유 엔드포인트용)로 실행됩니다.

왜 이 서버인가

대부분의 파일시스템 MCP 서버는 경로가 허용된 접두사로 시작하는지만 확인하고 그걸로 끝냅니다. 하지만 이는 중요한 세 가지를 놓칩니다:

• 심볼릭 링크. 샌드박스 안에 /etc를 가리키는 링크를 심어 두면 접두사 확인을 완전히 무력화합니다.

• 심볼릭 링크된 디렉터리를 통한 쓰기. realpath는 아직 존재하지 않는 경로에서 오류를 던지므로, 기존 파일만 확인하는 서버는 샌드박스 밖에 sandbox/linkdir/payload.sh를 생성하는 것을 그냥 허용합니다.

• 접두사 충돌. /data-secrets는 /data로 시작합니다.

이 서버는 결정하기 전에 모든 경로를 물리적 위치로 확인합니다. 대상이 아직 존재하지 않을 때는 가장 깊은 기존 상위 경로까지 올라가며, 구분자를 인식하는 매칭으로 realpath 처리된 루트와 비교합니다. 테스트 스위트는 이러한 탈출 시도가 각각 실패함을 검증합니다.

Related MCP server: MCP Filesystem Server

도구

쓰기는 원자적입니다. 콘텐츠는 같은 디렉터리의 임시 파일에 기록되고, fsync된 다음 대상 위로 이름이 바뀝니다. 충돌이 나거나 디스크가 가득 차도 원본은 잘리지 않고 그대로 유지됩니다.

빠른 시작

npm install
npm run build
npm test

그런 다음 클라이언트를 연결하세요:

node dist/index.js --root ./workspace

또는 클라이언트를 구성하지 않고 대화형으로 사용해 보세요:

npx @modelcontextprotocol/inspector node dist/index.js --root ./workspace

LM Studio

LM Studio는 ~/.lmstudio/mcp.json(Windows에서는 C:\Users\<you>\.lmstudio\mcp.json)을 읽습니다. 프로그램 → 설치 → mcp.json 편집에서 열고, mcpServers 아래에 항목을 추가한 다음 LM Studio를 다시 로드하세요.

네이티브로 실행하기

가장 마찰이 적은 옵션이며, 시작할 때 선택할 방법입니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-file-system/dist/index.js",
        "--root", "/absolute/path/to/your/project",
        "--read-only"
      ]
    }
  }
}

신뢰가 생기면 --read-only를 빼세요. 디렉터리를 더 추가하려면 --root 플래그를 더 추가하세요.

이 두 경로는 절대 경로여야 합니다. 호스트는 서버를 예측할 수 없는 작업 디렉터리에서 자식 프로세스로 실행하므로, 상대 경로는 해석되지 않습니다. 작업 디렉터리를 직접 제어하는 명령줄에서는 --root ./workspace 같은 상대 경로도 문제없습니다.

Windows에서는 슬래시(C:/Users/you/projects)를 쓰거나 백슬래시를 두 번 입력하세요. JSON 문자열 안에서 \ 하나는 이스케이프 문자이기 때문입니다.

Docker에서 실행하기

Docker는 서버 자체 검사 아래에 커널이 강제하는 경계를 제공하며, 이것이야말로 Docker를 사용해야 하는 진짜 이유입니다. 샌드박스 코드에 버그가 있더라도 마운트하지 않은 대상에는 도달할 수 없습니다.

docker build -t mcp-filesystem:latest .

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "--network", "none",
        "-v", "/absolute/path/to/your/project:/data:ro",
        "mcp-filesystem:latest",
        "--stdio", "--read-only"
      ]
    }
  }
}

참고:

• -i는 필수입니다. 이것이 없으면 컨테이너는 stdin을 받지 못하고 JSON-RPC 핸드셰이크가 결코 일어나지 않습니다. 이는 가장 흔한 잘못된 설정입니다.

• --network none은 설정할 가치가 있습니다. 이 서버는 네트워크에 연결할 이유가 없으며, 인터페이스를 제거하면 데이터 유출 가능성의 한 부류가 통째로 사라집니다.

• 마운트의 :ro는 읽기 전용 강제를 커널의 몫으로 만듭니다. 쓰기를 허용하려면 :ro를 빼고 그리고 --read-only도 빼세요.

• Docker는 -v의 호스트 쪽이 절대 경로일 것을 요구합니다.

• Windows용 Docker Desktop에서는 마운트할 드라이브가 설정 → 리소스 → 파일 공유에서 공유되어 있어야 합니다.

• Linux 호스트에서는 --user "$(id -u):$(id -g)"를 추가하여 생성된 파일이 uid 1000이 아니라 사용자 소유가 되도록 하세요.

-v를 반복하고 일치하는 --root 플래그를 전달하여 여러 디렉터리를 마운트하세요:

"-v", "/absolute/path/to/your/code:/data/code:ro",
"-v", "/absolute/path/to/your/notes:/data/notes",
"mcp-filesystem:latest",
"--stdio", "--root", "/data/code", "--root", "/data/notes"

HTTP 전송

여러 클라이언트가 공유하는 장기 실행 컨테이너의 경우:

docker compose up -d
curl http://127.0.0.1:3000/health

클라이언트를 http://127.0.0.1:3000/으로 연결하세요.

이 서버에는 인증이 없습니다. 포트에 접근할 수 있는 모든 사람은 서버가 가진 파일시스템 접근 권한을 그대로 가집니다. docker-compose.yml은 127.0.0.1에만 공개합니다. 다른 곳에 바인딩한다면 인증하는 리버스 프록시를 앞에 두고, 시작 로그가 경고를 띄울 것을 예상하세요.

루프백에 바인딩되면 서버는 DNS 리바인딩을 차단하기 위해 Host 및 Origin 헤더를 검증합니다. 즉, 방문한 웹 페이지가 공격자가 제어하는 도메인을 127.0.0.1로 해석하여 이 포트로 POST하는 것을 막습니다.

구성

모든 플래그에는 환경 변수에 해당하는 값이 있으며, 컨테이너는 이를 사용합니다. CLI 플래그가 우선합니다.

서버는 루트가 구성되지 않은 상태로 시작하는 것을 거부합니다. 샌드박스가 없는 파일시스템 서버는 안전한 기본값이 아니며, 작업 디렉터리를 기본값으로 삼는 것은 실수를 조용히 숨길 뿐입니다.

기본 차단 목록

--allow-default-denied를 전달하지 않는 한 차단됩니다: .env 및 .env.*, *.pem, *.key, *.p12, *.pfx, *.keystore, id_rsa/id_dsa/id_ecdsa/id_ed25519, .ssh/, .aws/, .gnupg/, .kube/config, .npmrc, .netrc, .pypirc, .docker/config.json, .git/, .svn/, .hg/, shadow.

이는 부주의한 -v $HOME:/data 마운트에서도 살아남을 수 있도록 하기 위한 것입니다. 올바른 디렉터리를 마운트하는 것의 대체물이 아니라 안전망입니다.

보안 모델

적용되는 것

• 모든 격리 결정 전에 물리적 경로 확인(realpath)을 수행하며, 아직 존재하지 않는 경로에도 적용

• 구분자를 인식하는 루트 매칭(/data는 /data-secrets와 절대 일치하지 않음)

• 심볼릭 링크는 기본적으로 거부되며, 경로의 마지막 요소뿐 아니라 모든 위치에서 거부

• NUL 바이트 거부(safe.txt\0/../../etc/passwd는 시스템 호출에서 잘림)

• Windows: 대체 데이터 스트림(file:stream), 예약된 장치 이름(CON, NUL, COM1…), 장치 네임스페이스 경로(\\?\, \\.\), 대소문자를 구분하지 않는 격리

• 읽기 전용 모드는 핸들러가 실행되기 전에 변경 도구를 차단

• move/copy에서 두 피연산자 모두 확인 — 소스만 확인하면 호스트 전체에 대한 쓰기 원시 연산이 됨

• 허용된 루트 자체는 삭제하거나 이동할 수 없음

• 할당 전 stat을 통해 크기 상한 확인

• 바이너리 감지를 통해 바이너리가 토큰을 낭비하는 쓰레기로 반환되지 않음

• grep_files에 정규식 사전 검증과 벽시계 기준 마감 시간 적용

• 오류 메시지는 호스트 경로를 절대 그대로 출력하지 않음. SecurityError는 모델에게 모호한 메시지를 반환하고 실제 이유는 감사 스트림에 기록하므로, 샌드박스가 파일시스템을 매핑하는 오라클이 되지 않음

적용되지 않는 것

• TOCTOU. 경로를 확인한 후 파일을 열기 전 사이에, 허용된 루트 안에 쓸 수 있는 로컬 공격자가 파일을 심볼릭 링크로 바꿔치기할 수 있습니다. 이를 막으려면 Linux의 openat2(RESOLVE_BENEATH)가 필요한데, Node는 이를 노출하지 않습니다. 실질적인 완화책은 컨테이너 경계입니다. 노출하려는 것만 마운트하세요.

• 인증. 두 전송 방식 모두 인증하지 않습니다. stdio는 프로세스를 실행한 주체의 신뢰를 물려받으며, HTTP는 그래서 루프백 전용입니다.

• 리소스 고갈. 상한과 마감 시간이 대부분을 제한하지만, 병적인 정규식은 여전히 15초짜리 CPU 마감 시간 하나를 소진할 수 있습니다. 컴포즈 파일에 메모리 및 CPU 제한이 설정되어 있습니다.

• 프롬프트 주입. 샌드박스 안의 파일에 지침이 포함되어 있고 모델이 이를 따른다면, 이 서버는 모델이 다음에 호출하는 도구를 충실히 실행합니다. 실제로 효과가 있는 완화책은 읽기 전용 모드입니다.

컨테이너 강화(docker-compose.yml): 비루트 사용자, read_only 루트 파일시스템, 모든 capability 제거, no-new-privileges, tmpfs /tmp, 메모리 및 CPU 제한.

감사 로그

stderr에 줄당 하나의 JSON 객체로 기록됩니다. stdout은 stdio에서 JSON-RPC 채널이므로 절대 사용하지 않습니다. console.log는 시작 시 stderr로 리디렉션되도록 monkey-patch되어, 우발적인 디버그 문이 프로토콜 스트림을 오염시킬 수 없습니다.

{"ts":"2026-08-21T19:12:03.441Z","tool":"read_file","outcome":"ok","durationMs":3,"paths":["src/index.ts"],"bytes":4821}
{"ts":"2026-08-21T19:12:07.882Z","tool":"read_file","outcome":"denied","durationMs":1,"detail":"physical containment failed: /data/../etc/passwd -> /etc/passwd"}

기록되는 경로는 샌드박스 기준 상대 경로입니다. detail 필드는 전체 이유를 담으며, 오직 여기에만 기록되고 모델에게는 절대 반환되지 않습니다.

docker compose logs -f filesystem | jq 'select(.outcome=="denied")'

테스트

npm run build && npm test

test/sandbox.test.ts가 중요한 테스트 스위트입니다. 모든 테스트 케이스는 루트 밖의 파일에 접근하려는 시도입니다. 그중 하나가 예외를 던져야 할 상황에서 통과하기 시작한다면, 서버는 진짜로 위험한 방식으로 손상된 것입니다.

심볼릭 링크 테스트는 Windows에서 개발자 모드가 켜져 있지 않으면 자신을 건너뜁니다. 그 외에는 심볼릭 링크를 만들려면 관리자 권한이 필요하기 때문입니다.

프로젝트 구조

src/
  index.ts              entrypoint, transport selection, shutdown
  config.ts             CLI + env parsing, root resolution
  security/
    sandbox.ts          path resolution and containment — the security core
    audit.ts            structured stderr logging, stdout protection
  tools/
    context.ts          registration wrapper: read-only gate, errors, audit
    read.ts             read_file, read_multiple_files, get_file_info, ...
    write.ts            write_file, append_file, edit_file
    listing.ts          list_directory, directory_tree
    manage.ts           create_directory, move_file, copy_file, delete_file
    search.ts           search_files, grep_files
  util/
    walk.ts             sandbox-aware directory traversal with cycle guard
    binary.ts           binary detection, BOM handling
    errors.ts           error taxonomy and fs error translation
    format.ts           output formatting for model consumption

라이선스

MIT