MCP Claude for Desktop 사용자를 위한 퀵스타트

원문: https://modelcontextprotocol.io/quickstart/user

Claude for Desktop에서 사전 구축된 서버를 사용하는 방법을 알아보세요.

이 튜토리얼에서는 Claude for Desktop을 확장하여 컴퓨터의 파일 시스템에서 파일을 읽고, 새 파일을 작성하고, 파일을 이동하고, 심지어 파일을 검색할 수 있게 만들 것입니다.

걱정하지 마세요 — 이러한 작업을 실행하기 전에 항상 여러분의 허가를 요청할 것입니다!

1. Claude for Desktop 다운로드

먼저 macOS 또는 Windows용 Claude for Desktop을 다운로드하세요. (Linux는 아직 Claude for Desktop에서 지원되지 않습니다.)

설치 지침을 따르세요.

이미 Claude for Desktop이 있다면, 컴퓨터에서 Claude 메뉴를 클릭하고 "업데이트 확인..."을 선택하여 최신 버전인지 확인하세요.

Claude for Desktop을 사용하는 이유는 무엇인가요?

서버가 로컬에서 실행되기 때문에 MCP는 현재 데스크톱 호스트만 지원합니다. 원격 호스트는 현재 개발 중입니다.

2. 파일시스템 MCP 서버 추가

이 파일시스템 기능을 추가하기 위해, 사전 구축된 파일시스템 MCP 서버를 Claude for Desktop에 설치할 것입니다. 이것은 Anthropic과 커뮤니티에서 만든 수십 개의 서버 중 하나입니다.

컴퓨터에서 Claude 메뉴를 열고 "설정..."을 선택하여 시작하세요. 앱 창 자체에 있는 Claude 계정 설정이 아니라는 점에 유의하세요.

Mac에서는 다음과 같이 보입니다:

설정 창의 왼쪽 바에서 "개발자"를 클릭한 다음 "구성 편집"을 클릭하세요:

이렇게 하면 다음 위치에 구성 파일이 생성됩니다 (아직 없는 경우):

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

그리고 파일 시스템에 파일이 표시됩니다.

아무 텍스트 편집기에서나 구성 파일을 열고, 파일 내용을 다음으로 바꾸세요:

MacOS/Linux

{
  "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을 컴퓨터의 사용자 이름으로 바꿔야 합니다. 경로는 Claude가 접근하고 수정할 수 있기를 원하는 유효한 디렉토리를 가리켜야 합니다. 데스크톱과 다운로드에서 작동하도록 설정되어 있지만 더 많은 경로를 추가할 수도 있습니다.

이것이 제대로 실행되려면 컴퓨터에 Node.js도 필요합니다. Node가 설치되어 있는지 확인하려면 컴퓨터에서 명령줄을 여세요.

macOS에서는 응용 프로그램 폴더에서 터미널을 엽니다
Windows에서는 Windows + R을 누르고 "cmd"를 입력한 다음 Enter를 누릅니다

명령줄에 들어가면 다음 명령을 입력하여 Node가 설치되어 있는지 확인하세요:

node --version

"command not found" 또는 "node is not recognized"와 같은 오류가 발생하면 nodejs.org에서 Node를 다운로드하세요.

구성 파일은 어떻게 작동하나요?

이 구성 파일은 Claude for Desktop에 애플리케이션을 시작할 때마다 시작할 MCP 서버를 알려줍니다. 이 경우에는 Node npx 명령을 사용하여 @modelcontextprotocol/server-filesystem을 설치하고 실행할 "filesystem"이라는 하나의 서버를 추가했습니다. 이 서버는 Claude for Desktop에서 파일 시스템에 접근할 수 있게 해줍니다.

명령 권한

Claude for Desktop은 구성 파일의 명령을 사용자 계정의 권한과 로컬 파일에 대한 액세스 권한으로 실행합니다. 소스를 이해하고 신뢰하는 경우에만 명령을 추가하세요.

3. Claude 재시작

구성 파일을 업데이트한 후에는 Claude for Desktop을 재시작해야 합니다.

재시작 후에는 입력 상자의 오른쪽 하단에 망치 아이콘이 표시되어야 합니다:

망치 아이콘을 클릭하면 파일시스템 MCP 서버와 함께 제공되는 도구가 표시되어야 합니다:

서버가 Claude for Desktop에 인식되지 않는 경우, 디버깅 팁을 위해 문제 해결 섹션으로 이동하세요.

4. 사용해 보기!

이제 Claude와 대화하며 파일시스템에 대해 물어볼 수 있습니다. Claude는 관련 도구를 호출할 시기를 알고 있어야 합니다.

다음과 같은 질문을 Claude에게 해볼 수 있습니다:

시를 작성하여 내 데스크톱에 저장해줄 수 있을까요?
다운로드 폴더에 있는 업무 관련 파일은 무엇인가요?
내 데스크톱에 있는 모든 이미지를 "Images"라는 새 폴더로 옮겨줄 수 있을까요?

필요에 따라 Claude는 관련 도구를 호출하고 조치를 취하기 전에 여러분의 승인을 구할 것입니다:

문제 해결

Claude에 서버가 표시되지 않음 / 망치 아이콘이 없음

Claude for Desktop을 완전히 재시작하세요
claude_desktop_config.json 파일 구문을 확인하세요
claude_desktop_config.json에 포함된 파일 경로가 유효하고 상대 경로가 아닌 절대 경로인지 확인하세요
서버가 연결되지 않는 이유를 보기 위해 로그를 확인하세요
명령줄에서 서버를 수동으로 실행해보세요 (claude_desktop_config.json에서 했던 것처럼 username을 바꿔서):

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 for Desktop에서 로그 가져오기

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

macOS: ~/Library/Logs/Claude
Windows: %APPDATA%\Claude\logs
mcp.log는 MCP 연결 및 연결 실패에 대한 일반적인 로깅을 포함합니다.
mcp-server-SERVERNAME.log라는 이름의 파일에는 명명된 서버의 오류(stderr) 로깅이 포함됩니다.

다음 명령을 실행하여 최근 로그를 나열하고 새로운 로그를 따라갈 수 있습니다(Windows에서는 최근 로그만 표시됩니다):

MacOS/Linux

# Claude의 로그에서 오류 확인
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Windows

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

도구 호출이 조용히 실패함

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

Claude의 로그에서 오류 확인
서버가 빌드되고 오류 없이 실행되는지 확인
Claude for Desktop 재시작 시도

모두 작동하지 않습니다. 어떻게 해야 하나요?

더 나은 디버깅 도구와 더 자세한 안내를 위해 디버깅 가이드를 참조하세요.

ENOENT 오류 및 Windows의 경로에 있는 `${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": "..."
    }
  }
}

이 변경 사항을 적용한 후 Claude Desktop을 다시 실행하세요.

NPM이 전역적으로 설치되어 있어야 합니다

NPM을 전역적으로 설치하지 않은 경우 npx 명령이 계속 실패할 수 있습니다. NPM이 이미 전역적으로 설치되어 있다면 시스템에 %APPDATA%\npm이 존재할 것입니다. 그렇지 않다면 다음 명령을 실행하여 NPM을 전역적으로 설치할 수 있습니다:

npm install -g npm

다음 단계

다른 서버 탐색하기: 공식 MCP 서버 및 구현 갤러리 확인하기
자체 서버 구축하기: 이제 Claude for Desktop 및 다른 클라이언트에서 사용할 수 있는 자체 사용자 정의 서버를 구축해 보세요

번역: https://modelcontextprotocol.io/quickstart/user

원문 출처 및 최신 정보는 위 링크를 참고하세요.

저작자표시 (새창열림)

MCP Claude for Desktop 사용자를 위한 퀵스타트

1. Claude for Desktop 다운로드

2. 파일시스템 MCP 서버 추가

MacOS/Linux

Windows

3. Claude 재시작

4. 사용해 보기!

문제 해결

Claude에 서버가 표시되지 않음 / 망치 아이콘이 없음

MacOS/Linux

Windows

Claude for Desktop에서 로그 가져오기

MacOS/Linux

Windows

도구 호출이 조용히 실패함

모두 작동하지 않습니다. 어떻게 해야 하나요?

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

다음 단계

티스토리툴바

ENOENT 오류 및 Windows의 경로에 있는 `${APPDATA}`