로컬 MCP 서버에 연결하기

로컬 MCP 서버에 연결하기 (Connect to local MCP servers)

로컬 MCP 서버로 Claude Desktop을 확장해서 파일시스템 접근과 그 밖의 강력한 통합을 가능하게 하는 방법을 배워요. MCP 서버는 로컬 리소스와 도구에 대한 안전하고 통제된 접근을 제공해 AI 애플리케이션의 기능을 확장해 줍니다.

출처: 문서

본문

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

이 가이드는 MCP를 지원하는 여러 클라이언트 중 하나인 Claude Desktop을 예로 들어 로컬 MCP 서버에 연결하는 방법을 보여 줍니다. Claude Desktop 구현에 초점을 맞추지만, 개념은 다른 MCP 호환 클라이언트에도 폭넓게 적용돼요. 이 튜토리얼이 끝나면 Claude는 각 작업에 대한 명시적 허가 하에, 컴퓨터의 파일과 상호작용하고 새 문서를 만들고 폴더를 정리하고 파일시스템을 검색할 수 있게 됩니다.

사전 요구 사항 (Prerequisites)

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

Claude Desktop

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

이미 Claude Desktop이 설치되어 있다면, Claude 메뉴를 클릭하고 "Check for Updates..."를 선택해 최신 버전을 실행 중인지 확인하세요.

Node.js

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

node --version

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

MCP 서버 이해하기

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

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

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

Filesystem Server 설치하기

이 과정은 Claude Desktop을 실행할 때마다 Filesystem Server를 자동으로 시작하도록 구성하는 작업이에요. 이 구성은 Claude Desktop에 어떤 서버를 실행하고 어떻게 연결할지를 알려 주는 JSON 파일을 통해 이루어집니다.

1단계: Claude Desktop 설정 열기

Claude Desktop 설정에 접근하는 것부터 시작하세요. 시스템 메뉴 막대의 Claude 메뉴(Claude 창 안의 설정이 아님)를 클릭하고 "Settings..."를 선택하세요.

macOS에서는 상단 메뉴 막대에 나타나요.

이렇게 하면 Claude 계정 설정과는 별개의 Claude Desktop 구성 창이 열립니다.

2단계: 개발자 설정 접근하기

Settings 창에서 왼쪽 사이드바의 "Developer" 탭으로 이동하세요. 이 섹션에는 MCP 서버와 기타 개발자 기능을 구성하는 옵션이 있어요.

"Edit Config" 버튼을 클릭해 구성 파일을 여세요.

이 작업은 구성 파일이 없으면 새로 만들고, 있으면 기존 파일을 열어요. 파일 위치는 다음과 같아요.

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

3단계: Filesystem Server 구성하기

구성 파일 내용을 다음 JSON 구조로 바꾸세요. 이 구성은 Claude Desktop에 특정 디렉터리에 접근하는 Filesystem Server를 시작하라고 알려 줍니다.

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

{
  "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 서버를 시작하려면 재시작이 필요해요.

재시작에 성공하면 대화 입력 상자 왼쪽 하단의 "Add files, connectors, and more /" 표시를 클릭하세요.

이 표시를 클릭한 다음 마우스를 "Connectors" 위에 올리고 "Manage connectors"를 클릭하세요. 커넥터 목록에서 "filesystem"을 선택해 Filesystem Server의 사용 가능한 도구를 확인해요.

Filesystem Server가 연결되지 않으면 문제 해결 섹션의 디버깅 단계를 참고하세요.

Filesystem Server 사용하기

Filesystem Server가 연결되면 Claude가 이제 파일시스템과 상호작용할 수 있어요. 다음 예시 요청을 시도해 기능을 살펴보세요.

파일 관리 예시

"시 한 편 써서 내 바탕화면에 저장해 줄래?" — Claude가 시를 짓고 바탕화면에 새 텍스트 파일을 만들어요.
"내 다운로드 폴더에 어떤 업무 관련 파일이 있니?" — Claude가 다운로드를 스캔해 업무 관련 문서를 식별해요.
"내 바탕화면의 모든 이미지를 'Images'라는 새 폴더로 정리해 줘" — Claude가 폴더를 만들고 이미지 파일을 그 안으로 옮겨요.

승인 방식

파일시스템 작업을 실행하기 전에 Claude는 승인을 요청합니다. 이렇게 해서 모든 동작에 대한 통제권을 유지하게 해 줘요.

승인하기 전에 각 요청을 주의 깊게 검토하세요. 제안된 동작이 편하지 않으면 언제든지 요청을 거부할 수 있어요.

문제 해결 (Troubleshooting)

Filesystem Server 설정이나 사용 중 문제가 발생하면 다음 해결책이 흔한 문제를 다룹니다.

서버가 Claude에 나타나지 않음 / 망치 아이콘 누락

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

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

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 출력이 포함됩니다. Stdio 서버는 모든 로깅에 stderr를 사용할 수 있으므로, 이 파일은 오류에 국한되지 않아요.

다음 명령으로 최근 로그를 나열하고 새 로그를 따라갈 수 있어요(Windows에서는 최근 로그만 표시):

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

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

도구 호출이 조용히 실패하는 경우

Claude가 도구를 사용하려 하지만 실패한다면:

오류를 위해 Claude의 로그를 확인하세요.
서버가 오류 없이 빌드되고 실행되는지 확인하세요.
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": "..."
    }
  }
}

이 변경 후 Claude Desktop을 다시 실행하세요.

npm은 전역으로 설치해야 합니다

npm을 전역으로 설치하지 않았다면 npx 명령이 계속 실패할 수 있어요. npm이 이미 전역으로 설치되어 있으면 시스템에 %APPDATA%\npm이 존재하는 것을 확인할 수 있어요. 아니라면 다음 명령으로 npm을 전역으로 설치할 수 있어요.

npm install -g npm

다음 단계

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

다른 서버 탐색하기 — 공식 및 커뮤니티에서 만든 MCP 서버 컬렉션 살펴보기
직접 서버 구축하기 — 특정 워크플로에 맞는 커스텀 MCP 서버 만들기
원격 서버 연결하기 — 클라우드 기반 도구와 서비스를 위해 Claude를 원격 MCP 서버에 연결하는 법
프로토콜 이해하기 — MCP가 어떻게 동작하고 그 아키텍처가 어떤지 심층 탐구

로컬 MCP 서버에 연결하기