로컬 MCP 서버 연결

Claude Desktop을 로컬 MCP 서버로 확장하여 파일 시스템 접근 및 기타 강력한 통합 기능을 활성화하는 방법을 알아봅니다.

Model Context Protocol(MCP) 서버는 로컬 리소스와 도구에 대한 안전하고 제어된 접근을 제공함으로써 AI 애플리케이션의 기능을 확장합니다. 많은 클라이언트가 MCP를 지원하여 다양한 플랫폼과 애플리케이션에서 다양한 통합 가능성을 제공합니다.

이 가이드는 MCP를 지원하는 많은 클라이언트 중 하나인 Claude Desktop을 예로 들어 로컬 MCP 서버에 연결하는 방법을 설명합니다. Claude Desktop의 구현에 집중하지만, 개념은 다른 MCP 호환 클라이언트에도 폭넓게 적용됩니다. 이 튜토리얼을 마치면 Claude가 컴퓨터의 파일과 상호작용하고, 새 문서를 만들고, 폴더를 구성하고, 파일 시스템을 검색할 수 있게 됩니다. 모든 작업은 사용자의 명시적인 허가가 있어야 합니다.

사전 요구사항

이 튜토리얼을 시작하기 전에 시스템에 다음이 설치되어 있는지 확인하세요.

Claude Desktop

운영 체제에 맞는 Claude Desktop을 다운로드하고 설치하세요. Claude Desktop은 macOS와 Windows에서 사용할 수 있습니다.

Claude Desktop이 이미 설치되어 있다면 Claude 메뉴를 클릭하고 "업데이트 확인..."을 선택하여 최신 버전인지 확인하세요.

Node.js

Filesystem Server와 많은 다른 MCP 서버는 Node.js가 필요합니다. 터미널 또는 명령 프롬프트를 열고 다음을 실행하여 Node.js 설치를 확인합니다.

node --version

Node.js가 설치되지 않았다면 nodejs.org에서 다운로드하세요. 안정성을 위해 LTS(장기 지원) 버전을 권장합니다.

MCP 서버 이해

MCP 서버는 컴퓨터에서 실행되며 표준화된 프로토콜을 통해 Claude Desktop에 특정 기능을 제공하는 프로그램입니다. 각 서버는 사용자의 승인 하에 Claude가 작업을 수행하는 데 사용할 수 있는 도구를 노출합니다. 설치할 Filesystem Server는 다음 도구를 제공합니다.

• 파일 내용 및 디렉터리 구조 읽기
• 새 파일 및 디렉터리 만들기
• 파일 이동 및 이름 변경
• 이름 또는 내용으로 파일 검색

모든 작업은 실행 전에 명시적인 승인이 필요하여, Claude가 접근하고 수정할 수 있는 것에 대한 완전한 제어권을 유지합니다.

Filesystem Server 설치

이 과정은 애플리케이션을 시작할 때마다 Claude Desktop이 Filesystem Server를 자동으로 시작하도록 구성하는 것입니다. 이 구성은 Claude Desktop에 실행할 서버와 연결 방법을 알려주는 JSON 파일을 통해 수행됩니다.

1단계: Claude Desktop 설정 열기

Claude Desktop 설정에 접근합니다. 시스템 메뉴 바의 Claude 메뉴(Claude 창 내부의 설정이 아님)를 클릭하고 "설정..."을 선택합니다.

macOS에서는 상단 메뉴 바에 나타납니다. 이렇게 하면 Claude 계정 설정과는 별도인 Claude Desktop 구성 창이 열립니다.

2단계: 개발자 설정 접근

설정 창에서 왼쪽 사이드바의 "개발자" 탭으로 이동합니다. 이 섹션에는 MCP 서버 구성 및 기타 개발자 기능 옵션이 포함되어 있습니다.

"구성 편집" 버튼을 클릭하여 구성 파일을 엽니다.

이 작업은 구성 파일이 없으면 새 파일을 만들고, 기존 구성이 있으면 엽니다. 파일 위치:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

3단계: Filesystem Server 구성

구성 파일의 내용을 다음 JSON 구조로 교체합니다. 이 구성은 특정 디렉터리에 대한 접근 권한으로 Filesystem Server를 시작하도록 Claude Desktop에 알립니다.

macOS:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Desktop",
        "C:\\Users\\username\\Downloads"
      ]
    }
  }
}

username을 실제 컴퓨터 사용자 이름으로 바꾸세요. args 배열에 나열된 경로는 Filesystem Server가 접근할 수 있는 디렉터리를 지정합니다. 필요에 따라 이 경로를 수정하거나 추가 디렉터리를 추가할 수 있습니다.

구성 이해

• "filesystem": Claude Desktop에 표시되는 서버의 이름
• "command": "npx": 서버 실행에 Node.js의 npx 도구 사용
• "-y": 서버 패키지 설치를 자동으로 확인
• "@modelcontextprotocol/server-filesystem": Filesystem Server의 패키지 이름
• 나머지 인수: 서버가 접근할 수 있는 디렉터리

보안 고려사항: Claude가 읽고 수정해도 괜찮은 디렉터리에만 접근 권한을 부여하세요. 서버는 사용자 계정 권한으로 실행되므로, 수동으로 수행할 수 있는 모든 파일 작업을 수행할 수 있습니다.

4단계: Claude Desktop 재시작

구성 파일을 저장한 후 Claude Desktop을 완전히 종료하고 재시작합니다. 애플리케이션이 새 구성을 로드하고 MCP 서버를 시작하려면 재시작이 필요합니다.

재시작에 성공하면 대화 입력 상자의 오른쪽 하단에 MCP 서버 표시기가 나타납니다. 이 표시기를 클릭하면 Filesystem Server에서 제공하는 사용 가능한 도구를 볼 수 있습니다.

서버 표시기가 나타나지 않으면 문제 해결 섹션을 참조하세요.

Filesystem Server 사용

Filesystem Server가 연결되면 Claude가 파일 시스템과 상호작용할 수 있습니다. 다음 예시 요청을 통해 기능을 탐색해 보세요.

파일 관리 예시

• "시를 써서 바탕화면에 저장해 줄 수 있나요?" — Claude가 시를 작성하고 바탕화면에 새 텍스트 파일을 만듭니다.
• "다운로드 폴더에 있는 업무 관련 파일은 무엇인가요?" — Claude가 다운로드를 스캔하고 업무 관련 문서를 식별합니다.
• "바탕화면의 모든 이미지를 'Images'라는 새 폴더에 구성해 주세요." — Claude가 폴더를 만들고 이미지 파일을 이동합니다.

승인 작동 방식

파일 시스템 작업을 실행하기 전에 Claude가 승인을 요청합니다. 이를 통해 모든 작업에 대한 제어권을 유지합니다. 승인 전에 각 요청을 주의 깊게 검토하세요. 제안된 작업이 불편하면 언제든지 거부할 수 있습니다.

문제 해결

Filesystem Server 설정 또는 사용 중 문제가 발생하면 다음 해결책을 참조하세요.

서버가 Claude에 표시되지 않는 경우

1. Claude Desktop을 완전히 재시작합니다.
2. claude_desktop_config.json 파일 구문을 확인합니다.
3. claude_desktop_config.json에 포함된 파일 경로가 유효하고 절대 경로인지(상대 경로가 아닌지) 확인합니다.
4. 로그를 확인하여 서버가 연결되지 않는 이유를 파악합니다.
5. 명령줄에서 서버를 수동으로 실행하여 오류가 있는지 확인합니다.

# macOS/Linux
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads

# Windows
npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads

Claude Desktop에서 로그 가져오기

MCP 관련 Claude.app 로깅은 다음 위치의 로그 파일에 기록됩니다.

• macOS: ~/Library/Logs/Claude

• Windows: %APPDATA%\Claude\logs

• mcp.log에는 MCP 연결 및 연결 실패에 대한 일반 로깅이 포함됩니다.

• mcp-server-SERVERNAME.log라는 파일에는 해당 서버의 오류(stderr) 로깅이 포함됩니다.

최근 로그를 나열하고 새 로그를 확인하려면 다음 명령어를 실행합니다.

# macOS/Linux
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows
type "%APPDATA%\Claude\logs\mcp*.log"

도구 호출이 자동으로 실패하는 경우

Claude가 도구를 사용하려고 하지만 실패하는 경우:

1. Claude 로그에서 오류를 확인합니다.
2. 서버가 오류 없이 빌드되고 실행되는지 확인합니다.
3. Claude Desktop을 재시작해 봅니다.

Windows에서 ENOENT 오류 및 경로의 ${APPDATA}

구성된 서버가 로드에 실패하고 로그에서 경로 내 ${APPDATA} 관련 오류가 표시되면 claude_desktop_config.json의 env 키에 %APPDATA%의 확장된 값을 추가해야 할 수 있습니다.

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
      "BRAVE_API_KEY": "..."
    }
  }
}

npm을 전역으로 설치해야 합니다: npm을 전역으로 설치하지 않은 경우 npx 명령어가 계속 실패할 수 있습니다. npm이 이미 전역으로 설치되어 있다면 시스템에 %APPDATA%\npm이 있습니다. 설치되지 않은 경우 다음 명령어로 npm을 전역으로 설치할 수 있습니다: npm install -g npm

다음 단계

Claude Desktop을 로컬 MCP 서버에 성공적으로 연결했으니 다음 옵션을 탐색하여 설정을 확장해 보세요.

• 다른 서버 탐색 — 공식 및 커뮤니티 MCP 서버 컬렉션을 탐색하여 추가 기능을 확인합니다.
• 자체 서버 구축 — 특정 워크플로우와 통합에 맞춘 맞춤형 MCP 서버를 만듭니다.
• 원격 서버 연결 — 클라우드 기반 도구와 서비스를 위해 Claude를 원격 MCP 서버에 연결하는 방법을 알아봅니다.
• 프로토콜 이해 — MCP의 작동 방식과 아키텍처를 더 깊이 이해합니다.

원문(영어): https://modelcontextprotocol.io/docs/develop/connect-local-servers · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/docs/develop/connect-local-servers