Claude가 직접 해결한 MCP Filesystem Server의 Windows UNC 경로 버그 수정

실용적 조언

Windows에서 MCP Filesystem 서버를 UNC 경로와 함께 사용할 때 접근 오류가 발생하면 path-validation.js 파일의 startsWith 로직을 확인하라.
네트워크 드라이브 매핑으로 문제를 해결하려 하기보다 UNC 경로 자체의 정규화 로직을 수정하는 것이 근본적인 해결책이다.
확장 프로그램 자동 업데이트 시 수동 패치가 덮어씌워질 수 있으므로 수정된 스크립트를 보관해두는 것이 좋다.

섹션별 상세

Windows UNC 경로(\\server\share\)를 사용 시 발생하는 특정 오류 증상을 확인했다. MCP Filesystem 서버의 list_directory 명령이 루트 디렉토리에서는 정상 작동하지만, 하위 폴더나 파일 작업 시에는 '허용된 디렉토리 외부의 경로'라는 에러와 함께 접근이 거부되는 현상이 나타났다.

설정 파일의 실제 위치를 파악하는 과정에서 혼선이 있었다. 일반적인 claude_desktop_config.json이 아닌, 데스크톱 확장으로 설치된 경우 %APPDATA% 내의 별도 JSON 파일에 설정이 저장됨을 확인했다. 또한 Node.js의 fs.realpath()가 매핑된 네트워크 드라이브를 다시 UNC 경로로 변환하여 문제를 우회하기 어렵게 만든다는 점을 발견했다.

버그의 근본 원인은 path-validation.js 내의 isPathWithinAllowedDirectories 함수 로직에 있었다. UNC 루트 경로는 이미 백슬래시로 끝나는데, 여기에 시스템 경로 구분자(path.sep)를 무조건 추가하면서 '\\server\share\\'와 같은 이중 백슬래시가 생성되어 실제 경로와 매칭되지 않는 결함이 확인됐다.

javascript

// 기존 버그가 있는 코드
return normalizedPath.startsWith(normalizedDir + path.sep);

UNC 경로 루트에서 이중 백슬래시 문제를 일으키는 기존 경로 검증 로직

해결을 위해 경로가 구분자로 끝나는지 여부를 먼저 확인하고 조건부로 구분자를 추가하도록 로직을 수정했다. 사용자는 PowerShell 스크립트를 작성하여 설치된 확장 프로그램의 배포용 JS 파일을 직접 패치했으며, 재시작 후 Claude가 스스로 MCP 도구를 사용하여 수정 사항을 검증하는 데 성공했다.

javascript

// 수정된 코드
const dirWithSep = normalizedDir.endsWith(path.sep) ? normalizedDir : normalizedDir + path.sep;
return normalizedPath.startsWith(dirWithSep);

경로 구분자가 이미 존재하는지 확인하여 중복 추가를 방지하는 수정 로직

powershell

$file = "$env:APPDATA\Claude\Claude Extensions\ant.dir.ant.anthropic.filesystem\node_modules\@modelcontextprotocol\server-filesystem\dist\path-validation.js"
$content = Get-Content $file -Raw
$content = $content.Replace(
    'return normalizedPath.startsWith(normalizedDir + path.sep);',
    'const dirWithSep = normalizedDir.endsWith(path.sep) ? normalizedDir : normalizedDir + path.sep; return normalizedPath.startsWith(dirWithSep);'
)
[System.IO.File]::WriteAllText($file, $content)

컴파일된 JS 파일에 패치를 직접 적용하는 PowerShell 스크립트

용어 해설

모델 컨텍스트 프로토콜(Model Context Protocol): — AI 모델이 로컬 파일 시스템, 데이터베이스, API 등 외부 데이터 소스 및 도구와 안전하게 상호작용할 수 있도록 Anthropic이 발표한 개방형 표준 프로토콜이다. 클라이언트와 서버 간의 표준화된 통신 규약을 제공하여 AI 에이전트의 확장성을 높인다.
범용 명명 규칙 경로(UNC Path): — 네트워크 공유 리소스를 식별하기 위한 표준 구문으로, Windows 환경에서 \\서버명\공유명 형식을 사용한다. 로컬 드라이브 문자가 아닌 네트워크 주소를 직접 참조하여 파일 시스템에 접근할 때 활용된다.
경로 검증(Path Validation): — 프로그램이 접근하려는 파일 경로가 보안상 허용된 디렉토리 범위 내에 있는지 확인하는 보안 메커니즘이다. 디렉토리 트래버설 공격을 방지하고 지정된 영역 외의 파일 접근을 차단하는 역할을 한다.

언급된 도구

MCP Filesystem Server추천

Claude가 로컬 파일 시스템에 접근할 수 있도록 하는 서버 확장

Claude Desktop추천

Anthropic의 공식 데스크톱 AI 클라이언트