M MCP모아
튜토리얼

Claude Desktop MCP 파일시스템 설정 — 로컬 폴더 접근 연결 가이드

Claude Desktop에서 server-filesystem MCP를 설정해 로컬 파일 읽기·쓰기를 활성화하는 방법을 단계별로 정리했습니다. Claude 파일 읽기 설정이 처음인 분께도 쉽게 따라올 수 있습니다.

Claude Desktop에 server-filesystem MCP 서버를 연결해 로컬 폴더에 접근하는 설정 가이드 표지

Claude Desktop에 server-filesystem MCP 서버를 연결하면 Claude가 지정한 로컬 폴더를 직접 읽고 쓸 수 있게 됩니다. 설정은 JSON 파일 한 곳만 수정하면 되며, Node.js만 설치돼 있으면 추가 패키지 설치 없이 npx로 즉시 실행됩니다. 이 가이드에서는 macOS·Windows·Linux 각각의 설정 파일 위치부터 흔한 오류 해결까지 한 번에 다룹니다.

왜 MCP 파일시스템 설정이 필요한가

기본 상태의 Claude Desktop은 대화창에 직접 붙여넣은 텍스트만 처리할 수 있습니다. 보고서 초안이나 코드 파일을 매번 복사해서 붙여넣는 작업은 번거롭고, 파일이 크면 아예 불가능합니다.

server-filesystem MCP를 연결하면 Claude가 허용된 디렉터리 안의 파일을 직접 읽고, 수정하고, 새로 만들 수 있습니다. 예를 들어 “Downloads 폴더의 보고서.docx 요약해줘”라고 말하면 Claude가 직접 파일을 열어 처리합니다.

사용자 지시
    │
    ▼
Claude Desktop (클라이언트)
    │  MCP 프로토콜
    ▼
server-filesystem MCP 서버 (npx 실행)
    │  allowedDirectories 범위 내
    ▼
로컬 파일 시스템 (읽기·쓰기·목록 조회)

준비물

항목요구 사항
Claude Desktop최신 버전(anthropic.com/claude에서 다운로드)
Node.jsv18 이상 (LTS 권장)
텍스트 편집기VS Code, 메모장 등 JSON 편집 가능한 모든 편집기

Node.js 버전 확인 방법:

node -v
# v20.x.x 이상이면 정상

단계별 설정 방법

1단계: 설정 파일 위치 확인

운영체제별로 claude_desktop_config.json 경로가 다릅니다.

운영체제경로
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
Linux~/.config/Claude/claude_desktop_config.json

파일이 없으면 직접 생성하면 됩니다.

2단계: 설정 파일 열기

macOS / Linux:

# VS Code로 열기
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 또는 기본 텍스트 편집기로
open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows (PowerShell):

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

3단계: filesystem 서버 설정 추가

claude_desktop_config.json에 아래 내용을 작성합니다. allowedDirectories의 경로는 실제 접근을 허용할 폴더로 바꾸세요.

macOS 예시:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/사용자명/Documents",
        "/Users/사용자명/Downloads"
      ]
    }
  }
}

Windows 예시:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:/Users/사용자명/Documents",
        "C:/Users/사용자명/Downloads"
      ]
    }
  }
}

보안 주의: C:/ 나 / 같은 최상위 루트 경로는 절대 지정하지 마세요. 꼭 필요한 폴더만 명시적으로 등록해야 합니다.

이미 다른 MCP 서버가 설정돼 있다면 mcpServers 객체 안에 filesystem 키만 추가하면 됩니다:

{
  "mcpServers": {
    "기존서버": {
      "command": "...",
      "args": ["..."]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/사용자명/Documents"
      ]
    }
  }
}

4단계: Claude Desktop 완전 재시작

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료합니다. macOS는 메뉴 바의 Claude 아이콘에서 “Quit Claude”를 선택하고, Windows는 시스템 트레이 아이콘을 우클릭해 종료해야 백그라운드 프로세스까지 완전히 끝납니다. 이후 Claude Desktop을 다시 실행합니다.

5단계: 연결 확인

Claude 대화창에 아래처럼 입력해 정상 동작을 확인합니다:

내 Documents 폴더에 어떤 파일이 있어?

파일 목록이 응답되면 설정 성공입니다. 이후 “보고서.txt 내용 요약해줘”, “새 파일 만들어줘” 같은 명령을 바로 사용할 수 있습니다.

흔한 오류와 해결 방법

JSON 문법 오류

설정 파일에 쉼표가 빠지거나 따옴표가 맞지 않으면 Claude Desktop이 MCP 서버를 인식하지 못합니다. JSONLint 같은 온라인 검사 도구에 설정 내용을 붙여넣어 문법을 확인하세요.

”MCP server not found” 메시지

npx가 패키지를 받지 못한 경우입니다. 인터넷 연결을 확인하고, 터미널에서 직접 실행해 오류 메시지를 확인하세요:

npx -y @modelcontextprotocol/server-filesystem /tmp

경로를 찾지 못함

경로에 한글이나 공백이 포함된 경우 인식이 안 될 수 있습니다. 경로 자체는 JSON 문자열이므로 이미 따옴표 안에 있지만, macOS/Linux에서 직접 터미널로 테스트할 때는 따옴표로 감싸서 확인합니다.

Node.js 버전 문제

Node.js 16 이하 버전에서는 동작하지 않을 수 있습니다. node -v로 버전을 확인하고, nodejs.org에서 LTS 버전으로 업그레이드하세요.

한국어 문서 파일도 처리하고 싶다면

로컬 파일시스템 접근이 가능해졌다면 HWP·HWPX·PDF 같은 한국어 문서 파일도 Claude와 함께 처리할 수 있습니다. 다음 MCP 서버들을 추가로 연결해 보세요.

  • 코르독(KorDoc) — HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 Markdown으로 변환하는 MCP 서버입니다.

    npx -y kordoc setup

  • HWP-MCP — AI 어시스턴트가 한글(.hwp/.hwpx) 문서를 읽고 편집·생성할 수 있게 해주는 MCP 서버입니다.

    npx -y hwp-mcp

  • 한포지(HwpForge) — 한글(HWPX) 문서를 AI 에이전트가 읽고 쓰고 변환할 수 있게 해주는 MCP 서버입니다.

    npx -y @hwpforge/mcp

이 서버들은 개발도구 카테고리에서 더 찾아볼 수 있습니다.

자주 묻는 질문

Claude Desktop에서 MCP 파일시스템 설정을 하면 모든 폴더에 접근할 수 있나요?

아니요. allowedDirectories에 명시적으로 지정한 경로만 접근 가능합니다. 보안을 위해 필요한 폴더만 최소한으로 등록하는 것을 권장합니다.

설정 후 Claude가 파일을 인식하지 못합니다. 어떻게 해야 하나요?

claude_desktop_config.json의 JSON 문법 오류 여부를 확인하고, Claude Desktop을 완전히 종료(트레이 아이콘까지 종료) 후 재시작하세요. 경로에 한글이나 공백이 있으면 큰따옴표로 감싸야 합니다.

Windows에서 경로는 어떻게 작성하나요?

Windows 경로는 역슬래시 대신 슬래시(/)를 사용하거나, 역슬래시를 두 번(\\) 써야 JSON에서 올바르게 인식됩니다. 예: C:/Users/사용자명/Documents

server-filesystem MCP는 파일 쓰기도 가능한가요?

네, 읽기뿐 아니라 쓰기·삭제·이동 등 파일 시스템 조작이 가능합니다. 다만 allowedDirectories 범위 내에서만 동작하며, 민감한 시스템 폴더는 절대 포함하지 마세요.

Claude Code와 Claude Desktop은 MCP 설정이 다른가요?

네. Claude Code는 프로젝트별 .mcp.json 또는 전역 ~/.config/claude/settings.json을 사용합니다. 이 가이드는 Claude Desktop(데스크탑 앱)의 claude_desktop_config.json 설정 방법을 다룹니다.

허용 디렉터리를 여러 개 지정할 수 있나요?

네, args 배열에 원하는 경로를 여러 개 나열할 수 있습니다. 위의 예시처럼 Documents와 Downloads를 동시에 등록하는 방식입니다.

다음 단계

파일시스템 MCP 설정을 완료했다면, 다른 MCP 서버를 추가해 Claude의 능력을 더 확장해 보세요. 전체 MCP 서버 목록에서 업무에 맞는 서버를 찾아볼 수 있습니다. MCP 서버를 직접 만들었거나 알고 있다면 등록 신청도 환영합니다.

이 글과 관련된 MCP 서버