Claude MCP 서버 설치하고 파일시스템 연동하는 완벽 가이드

Claude에서 로컬 파일을 자유롭게 읽고 쓰려면 MCP(Model Context Protocol) 서버를 설치해야 해요. 생각보다 간단한데, 처음 하시는 분들은 어디서부터 시작해야 할지 막막하실 거예요.

 

macOS에서 Claude Desktop과 파일시스템을 연동하는 과정을 차근차근 설명해드릴게요. 코드 예시도 많이 준비했으니 그대로 따라하시면 돼요.

 

Node.js 먼저 설치하세요

 

MCP 서버를 실행하려면 Node.js가 꼭 필요해요. 공식 홈페이지에서 다운로드하거나 Homebrew로 설치하면 돼요.

# Homebrew로 설치하는 방법
brew install node

# 설치 확인
node --version
npm --version

 

설치가 완료되면 터미널에서 버전이 표시돼요. 이제 다음 단계로 넘어가요.

 

Claude Desktop 개발자 모드 켜기

 

Claude Desktop 앱을 실행하고 상단 메뉴에서 설정을 변경해야 해요.

 

1. Claude Desktop 실행
2. 상단 메뉴 → Help → Developer Mode 클릭
3. 앱 재시작

 

개발자 모드를 켜면 MCP 서버 설정을 편집할 수 있게 돼요.

 

설정 파일 찾아서 열기

 

macOS에서 Claude 설정 파일은 특정 경로에 숨어있어요. 터미널을 열고 다음 명령어를 입력하세요.

# 설정 파일 경로로 이동
cd ~/Library/Application\ Support/Claude/

# 파일 확인
ls -la

# 텍스트 에디터로 열기 (예: nano)
nano claude_desktop_config.json

 

파일이 없다면 새로 만들어야 해요. Claude Desktop에서 Settings → Developer → Edit Config를 클릭하면 자동으로 열려요.

 

반응형

 

파일시스템 MCP 서버 설정하기

 

이제 가장 중요한 부분이에요. 설정 파일에 MCP 서버 정보를 추가해야 해요.

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

 

사용자이름 부분은 실제 macOS 계정명으로 바꿔주세요. 터미널에서 whoami 명령어로 확인할 수 있어요.

 

여러 폴더를 추가하고 싶다면 args 배열에 경로를 더 넣으면 돼요. 보안을 위해 꼭 필요한 폴더만 추가하는 게 좋아요.

 

GitHub MCP 서버도 함께 설정하기

 

GitHub 리포지토리와 연동하고 싶다면 GitHub MCP 서버도 추가할 수 있어요. 먼저 GitHub Personal Access Token을 만들어야 해요.

 

GitHub 웹사이트에서:

 

1. Settings → Developer settings → Personal access tokens
2. Fine-grained tokens → Generate new token
3. 권한 설정: read:packages, repo 선택
4. 토큰 복사 (한 번만 보여줘요!)

 

이제 설정 파일에 GitHub 서버를 추가해요.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/사용자이름/Desktop",
        "/Users/사용자이름/Documents"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "여기에_토큰_붙여넣기"
      }
    }
  }
}

 

Docker 대신 npx로 GitHub MCP 실행하기

 

macOS에서는 Docker보다 npx를 사용하는 게 더 간편해요. 위 예시처럼 npx 명령어로 GitHub MCP를 실행할 수 있어요.

 

만약 Docker를 선호한다면 이렇게 설정하세요.

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN=토큰값",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

 

설정 저장하고 Claude 재시작하기

 

설정 파일을 저장한 후 Claude Desktop을 완전히 종료했다가 다시 실행해요.

# Claude 프로세스 확인
ps aux | grep Claude

# 강제 종료 (필요시)
killall Claude

# 다시 실행
open -a "Claude"

 

정상적으로 연동되면 채팅창 하단이나 우측에 망치 모양 아이콘이 나타나요.

 

MCP 기능 테스트해보기

 

이제 Claude에서 파일시스템과 GitHub에 접근할 수 있어요. 다음과 같은 명령어를 시도해보세요.

"데스크톱 폴더에 있는 파일 목록 보여줘"
"Documents 폴더에 test.txt 파일 만들어줘"
"내 GitHub 리포지토리 목록 알려줘"
"README.md 파일 내용 읽어줘"

 

처음 사용할 때 권한 요청 팝업이 뜰 수 있어요. 승인하면 계속 사용할 수 있어요.

 

자주 발생하는 문제 해결하기

 

설정이 안 될 때 확인해볼 사항들이에요.

 

MCP 아이콘이 안 보일 때:

• JSON 문법 오류 확인 (쉼표, 중괄호)
• Claude Desktop 개발자 모드 활성화 확인
• 앱 완전 재시작

 

파일 접근 오류가 날 때:

# 폴더 권한 확인
ls -la ~/Desktop

# 권한 변경 (필요시)
chmod 755 ~/Desktop

 

npx 명령어가 안 될 때:

# npm 캐시 정리
npm cache clean --force

# npx 재설치
npm install -g npx

 

여러 MCP 서버 동시에 사용하기

 

파일시스템, GitHub 외에도 다양한 MCP 서버를 추가할 수 있어요.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/사용자이름/Desktop"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "토큰값"
      }
    },
    "google-drive": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-gdrive"
      ]
    }
  }
}

 

각 서버마다 고유한 이름을 지정하고, 필요한 환경 변수를 설정하면 돼요.

 

보안 주의사항

 

MCP 서버를 설정할 때 보안을 꼭 신경 써야 해요.

 

• 민감한 폴더는 접근 권한에서 제외
• GitHub 토큰은 최소 권한만 부여
• 설정 파일은 다른 사람과 공유하지 않기
• 정기적으로 토큰 갱신하기

 

터미널에서 다음 명령어로 설정 파일 권한을 제한할 수 있어요.

chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

 

이렇게 설정하면 본인만 읽고 쓸 수 있어요.

 

Claude MCP 서버 설정이 완료되면 로컬 파일을 자유롭게 다룰 수 있고, GitHub 리포지토리도 직접 관리할 수 있어요. 처음엔 복잡해 보여도 한 번 설정해두면 정말 편리하게 사용할 수 있어요.

 

 

2025.06.16 - [IT] - Claude AI 외부 앱 연동하는 방법: Zapier, Jira 등 수천 개 앱과 연결하기

Claude AI 외부 앱 연동하는 방법: Zapier, Jira 등 수천 개 앱과 연결하기