fs-mcp

여섯 가지 도구를 제공하는 초소형 MCP 서버:

1. explore_filesystem(subpath?, glob?) — 루트 디렉터리 아래의 파일/폴더를 나열하며, 선택적으로 glob(**/*.js 등)으로 필터링할 수 있습니다.

2. edit_file(path, edits[], createIfMissing?) — 루트 아래의 파일에 git 스타일의 줄 편집(줄 범위 교체/삽입/삭제)을 적용합니다.

3. create_file(path, content?, overwrite?) — 선택적 콘텐츠로 새 파일을 만들고, 필요에 따라 상위 디렉터리도 생성합니다.

4. delete_file(path, recursive?) — 루트 아래의 파일 또는 디렉터리를 삭제합니다(비어 있지 않은 디렉터리는 선택적으로 재귀 삭제).

5. read_file(path, startLine?, endLine?) — 파일 콘텐츠를 읽으며, 선택적으로 줄 범위로 제한하고 줄 번호를 접두사로 붙입니다.

6. grep(pattern, glob?, useRegex?, caseInsensitive?) — 파일에서 텍스트 패턴을 검색하며, 선택적으로 정규식 지원과 glob 필터링을 제공합니다.

루트 = 프로세스가 시작될 때 작업 디렉터리가 있는 위치입니다.

전역 CLI로 설치

npm install
npm link          # or: npm install -g .

이렇게 하면 전역 fs-mcp 명령이 생깁니다(package.json의 bin 필드를 통해 연결됨).

Related MCP server: LocalFS MCP Server

실행

fs-mcp                 # stdio mode (default) — for Claude Desktop/Code,
                        # which spawn the process themselves
fs-mcp --http          # HTTP mode on http://localhost:4823/mcp — for
                        # curl, the MCP Inspector, or the on-demand
                        # Claude Desktop setup below
fs-mcp --http -p 5000   # custom port
fs-mcp --help

실행할 때 서 있는 폴더가 노출되는 루트가 됩니다.

Claude Desktop에 연결

Claude Desktop은 MCP 서버를 직접 생성하고 stdio로 통신합니다. 터미널의 현재 디렉터리를 상속하지 않습니다. 따라서 작업 방식에 따라 두 가지 설정 옵션이 있습니다:

옵션 A — 모든 폴더에서 온디맨드(CLI 느낌을 원하면 권장)

Desktop을 한 번만 구성하고, 고정된 폴더가 아닌 고정된 로컬 포트를 가리키게 합니다. claude_desktop_config.example.json을 참조하세요. 해당 파일의 "fs-mcp" 항목을 기존 mcpServers 객체에 병합하세요:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Claude Desktop을 한 번 재시작합니다. 그 후부터:

cd ~/whatever/project
fs-mcp --http

그 폴더가 서버가 실행되는 동안 Claude가 볼 수 있는 대상이 됩니다. Ctrl+C로 종료하고 다른 폴더에서 다시 시작하면 컨텍스트가 전환됩니다. Desktop 구성 변경은 더 이상 필요 없습니다.

참고: --allow-http가 필요한 이유는 mcp-remote(stdio↔HTTP 브리지)가 기본적으로 실제 원격 서버에 HTTPS + OAuth를 기대하기 때문입니다. 이 플래그는 인증되지 않은 일반 localhost 트래픽이 괜찮다고 알려줍니다.

옵션 B — 하나의 고정 폴더, 항상 사용 가능

Desktop이 항상 같은 프로젝트를 노출하도록 하고 싶다면, 수동으로 시작할 필요 없이:

{
  "mcpServers": {
    "fs-mcp": {
      "command": "fs-mcp",
      "cwd": "/absolute/path/to/the/folder/you/want/exposed"
    }
  }
}

Desktop을 재시작합니다. 이 방식은 stdio 모드를 직접 사용합니다. 프록시나 수동 fs-mcp --http 단계가 없지만, 노출 폴더를 변경하려면 이 구성을 편집하고 Desktop을 다시 재시작해야 합니다.

보안 참고 사항

• 모든 경로는 루트를 기준으로 확인되며, 루트를 벗어나면 거부됩니다(예: ../../etc/passwd) — 경로 탐색 테스트로 검증됨.

• 인증이 없습니다. 서버에 도달할 수 있는 모든 것(--http 모드에서는 모든 로컬 프로세스)이 루트 아래의 모든 파일을 읽고 쓸 수 있습니다. 신뢰할 수 있는 로컬 개발 용도로는 괜찮지만, 민감한 곳에서 실행하지 말고 localhost 이상으로 바인딩하지 마세요.

편집 의미(edit_file)

편집은 {startLine, endLine, newLines}이며, 1부터 시작하는 인덱스로 포함됩니다:

• 3~5행 교체: {startLine: 3, endLine: 5, newLines: ["new content"]}

• 3~5행 삭제: {startLine: 3, endLine: 5, newLines: []}

• 6행 앞에 삽입(삭제 없음): {startLine: 6, endLine: 5, newLines: ["inserted"]}

한 번의 호출에서 여러 편집은 내부적으로 아래에서 위로 적용되므로, 편집 목록의 줄 번호는 이전 편집이 적용되면서 이동하지 않습니다.