macOS Claude Desktop에서 filesystem MCP를 이용한 로컬 파일 직접 조작 설정 방법

최근 화제가 되고 있는 MCP (Model Context Protocol). 그중에서도 로컬 PC의 파일을 AI가 직접 조작할 수 있게 해주는 filesystem 서버는 개발 경험을 극적으로 향상시키는 강력한 도구입니다.

얼마 전, Claude Desktop 앱이 MCP를 지원하게 되면서 이 filesystem 서버를 간편하게 통합할 수 있게 되었습니다.

본 기사에서는 macOS 환경의 Claude Desktop에 @modelcontextprotocol/server-filesystem을 도입하여, 로컬의 특정 디렉토리(이번에는 Desktop)에 접근해 파일 조작을 수행하기까지의 구체적인 설정 절차와 실수하기 쉬운 주의점을 해설합니다.

• macOS (Apple Silicon 환경 가정)
• Claude Desktop 앱
• Homebrew + Node.js 환경

이번에 이용할 @modelcontextprotocol/server-filesystem은 MCP의 공식 레퍼런스 구현으로서 제공되는 Node.js 기반의 MCP 서버(npm 패키지)입니다.

단순한 프로그램이 아니라, Claude (LLM)와 사용자의 로컬 PC 파일 시스템을 연결하는 '안전한 중개자 (Bridge)'로서 기능합니다.

구체적으로는 Claude에게 다음과 같은 '도구 (Tool/기능)'를 표준화된 API로서 제공합니다.

• 파일 읽기 및 쓰기 (read_file, write_file)
• 디렉토리 탐색 (list_directory, list_allowed_directories)
• 파일 검색 (search_files)
• 파일 정보 취득 (get_file_info)

【보안 측면에서의 강력한 특징】

가장 중요한 점으로서, 이 서버는 '기동 시 인자(Argument)로 명시적으로 지정한 디렉토리(및 그 하위 디렉토리)'에만 접근을 허용합니다.

이번처럼 /Users/kooohei/Desktop이라고 지정하면, 시스템 파일이나 다른 프로젝트의 폴더에는 Claude 측에서 절대 변경하거나 접근할 수 없도록, 패스 트래버설 (Path Traversal/디렉토리 트래버설) 공격 등을 방지하는 견고한 설계로 되어 있습니다.

먼저 터미널을 열고, npx 명령어를 사용할 수 있는지와 그 경로를 확인합니다.

which npx
which node
node -v

저의 환경 (Apple Silicon Mac)에서는 다음과 같이 나왔습니다. Homebrew로 설치한 경우, /opt/homebrew/bin/ 하위가 되는 케이스가 많습니다.

/opt/homebrew/bin/npx
/opt/homebrew/bin/node
v25.4.0

Claude Desktop의 MCP 설정 파일을 작성 또는 편집합니다. macOS의 경우 다음 경로입니다.

~/Library/Application Support/Claude/claude_desktop_config.json

※ 파일이 존재하지 않는 경우, 새로 생성해 주세요.

설정 파일에 다음 JSON을 기술합니다.

{
  "mcpServers": {
    "filesystem": {
      ...
    }
  }
}

【설정 항목 해설】

• mcpServers: 연동할 MCP 서버를 정의하는 큰 틀의 항목입니다. 여기에 여러 서버를 추가해 나갈 수 있습니다.
• filesystem: 이번에 추가할 서버의 식별명입니다. Claude Desktop의 UI (커넥터 화면)에는 이 이름이 표시됩니다. 임의의 이름으로 정해도 무방합니다.
• command: 실행할 명령어입니다. 환경 변수 (Path) 읽기 에러를 방지하기 위해, 단계 1에서 확인한 npx의 절대 경로를 지정할 것을 강력히 권장합니다.
• args: 명령어에 전달할 인자를 배열로 지정합니다 (※ arg가 아니라 args라는 점에 주의).
• "-y": npx 실행 시

`: 실제로 실행할 MCP 서버의 npm 패키지 이름입니다.

• "/Users/kooohei/Desktop":

:Claude가 접근을 허용할 디렉터리의 절대 경로입니다. 이 부분을 수정함으로써 Claude가 접근할 수 있는 범위를 제어할 수 있습니다. 여러 개를 지정하고 싶다면, "/Users/kooohei/Desktop", "/Users/kooohei/Downloads"와 같이 배열의 요소로서 이어서 기술합니다.

설정을 반영하기 위해 Claude Desktop을 재시작합니다. Dock에서 닫는 것만으로는 백그라운드에 프로세스가 남아 있을 수 있으므로, 명령어를 통해 완전히 종료하는 것이 확실합니다.

killall Claude
open -a Claude

연동이 잘 되지 않는다면 먼저 로그를 확인해 봅시다.

cat ~/Library/Logs/Claude/mcp-server-filesystem.log

정상적으로 기동 중이라면, Server started and connected successfully와 같은 로그가 기록됩니다. 또한, 로그 내에 tools/list와 같은 표기가 있다면 Claude Desktop 측에서 filesystem MCP를 올바르게 인식하고 있는 것입니다.

Claude Desktop의 채팅 입력창 왼쪽 하단에 있는 「＋」 아이콘을 클릭하고, 「커넥터 (Connector)」(또는 도구 액세스)를 엽니다.

여기에서 filesystem이 표시되어 있다면 연동에 성공한 것입니다.

연동이 완료되었더라도 갑자기 다음과 같이 질문하면……

Desktop 하위의 파일 목록을 표시해 주세요.

이미지와 같이 "제가 사용할 수 있는 것은 클라우드 상의 컨테이너 환경뿐이며..."라며 filesystem 도구를 이용하지 않고 일반적인 답변(에러)을 내놓는 경우가 있습니다. 이는 도구가 제대로 호출되지 않은 상태입니다.

입력창의 「＋」에서 filesystem의 토글 스위치를 명시적으로 ON으로 설정한 상태에서, 다시 동일한 프롬프트를 실행해 보세요.

그러면 이번에는 "filesystem 연동을 사용했습니다"라는 표시와 함께, 로컬 Desktop 하위의 파일 목록을 멋지게 가져옵니다.

▲ filesystem이 실제로 이용되어 로컬 파일 목록을 가져온 상태

본 기사에서는 Claude Desktop에서 로컬 파일을 직접 조작하기 위한 filesystem MCP 설정 절차를 소개해 드렸습니다.

도입함으로써 다음과 같은 조작을 Claude와 대화하며 직접 수행할 수 있게 됩니다.

• 로컬 파일 목록 가져오기
• 파일 내용 읽기
• 파일 편집 및 코드 자동 수정

브라우저 버전에서 매번 파일을 업로드하거나 코드를 복사하여 붙여넣는 번거로움을 줄일 수 있으므로, 한 번 설정해 두면 일상적인 작업 효율이 격상됩니다. 또한, 이번 설정과 같이 액세스 허용을 특정 폴더로만 한정함으로써 보안 측면을 제어하며 이용할 수 있다는 점도 장점입니다.

MCP에는 filesystem 외에도 GitHub, Notion, 데이터베이스 등과 연동할 수 있는 다양한 서버가 준비되어 있습니다. 우선 도입이 간단하고 효과를 실감하기 쉬운 filesystem부터 MCP의 압도적인 편리함을 꼭 체험해 보시기 바랍니다!