Skip to content

로컬 서버 연결 (Connect Local Servers)

MCP(Model Context Protocol) 서버는 AI 애플리케이션의 기능을 확장해 줘요. 로컬 리소스와 도구에 안전하게, 그리고 통제된 방식으로 접근할 수 있게 해주는 역할을 하죠. 이 문서에서는 그중 한 클라이언트인 Claude Desktop을 예시로 로컬 MCP 서버에 연결하는 방법을 살펴볼게요. Claude Desktop의 구현을 중심으로 설명하지만, 그 개념은 다른 MCP 호환 클라이언트에도 그대로 적용돼요.

이 튜토리얼을 마치면 Claude가 여러분 컴퓨터의 파일을 읽고, 새 문서를 만들고, 폴더를 정리하고, 파일 시스템을 검색할 수 있게 됩니다. 모든 동작은 각 단계마다 여러분의 명시적 허가를 받아 이루어져요.

사전 준비 (Prerequisites)

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

Claude Desktop

운영체제에 맞는 Claude Desktop을 다운로드해서 설치하세요. Claude Desktop은 macOS와 Windows에서 사용할 수 있어요. 이미 설치되어 있다면 Claude 메뉴를 클릭하고 "Check for Updates…"를 선택해 최신 버전인지 확인해 보세요.

Node.js

Filesystem Server를 포함한 많은 MCP 서버는 실행에 Node.js가 필요해요. 터미널이나 명령 프롬프트를 열고 아래 명령으로 Node.js 설치 여부를 확인해 보세요.

node --version

Node.js가 없다면 nodejs.org에서 다운로드하세요. 안정성을 위해 LTS(Long Term Support) 버전을 권장해요.

MCP 서버 이해하기 (Understanding MCP Servers)

MCP 서버는 여러분 컴퓨터에서 실행되는 프로그램으로, 표준화된 프로토콜을 통해 Claude Desktop에 특정 기능을 제공해요. 각 서버는 Claude가 동작을 수행할 때 쓸 수 있는 도구(tools)를 노출하며, 이때 여러분의 승인이 필요하죠. 이번에 설치할 Filesystem Server가 제공하는 도구는 다음과 같아요.

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

모든 동작은 실행 전에 여러분의 명시적 승인을 요구하므로, Claude가 무엇에 접근하고 무엇을 수정할 수 있는지에 대한 통제권을 항상 지킬 수 있어요.

Filesystem Server 설치하기 (Installing the Filesystem Server)

이 과정의 핵심은 Claude Desktop이 실행될 때마다 Filesystem Server를 자동으로 시작하도록 설정하는 거예요. 이 설정은 JSON 파일로 하게 되는데, 이 파일이 Claude Desktop에 어떤 서버를 실행하고 어떻게 연결할지 알려줘요.

1. Claude Desktop 설정 열기

Claude Desktop 설정에 접근하세요. 시스템 메뉴 막대의 Claude 메뉴를 클릭하고(Claude 창 내부의 설정이 아니라요) "Settings…"를 선택하세요. macOS에서는 상단 메뉴 막대에 이 옵션이 나타나요. 그러면 Claude 계정 설정과는 별개인 Claude Desktop 구성 창이 열립니다.

2. 개발자 설정 접근하기

설정 창에서 왼쪽 사이드바의 "Developer" 탭으로 이동하세요. 이 섹션에는 MCP 서버 및 기타 개발자 기능을 구성하는 옵션이 있어요. "Edit Config" 버튼을 클릭해 구성 파일을 엽니다. 구성 파일이 없다면 새로 만들어지고, 있으면 기존 파일이 열려요. 파일 위치는 다음과 같아요.

  • 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 서버를 시작하니까요. 성공적으로 재시작되면 대화 입력창 왼쪽 하단의 "Add files, connectors, and more /" 표시기를 클릭하세요. 그런 다음 이 표시기에서 "Connectors" 위로 마우스를 옮기고 "Manage connectors"를 클릭해서, 커넥터 목록에서 "filesystem"을 선택하면 Filesystem Server가 제공하는 도구를 볼 수 있어요.

Filesystem Server가 연결되지 않는다면 Troubleshooting 섹션에서 디버깅 단계를 확인하세요.

Filesystem Server 사용하기 (Using the Filesystem Server)

Filesystem Server가 연결되면 Claude가 파일 시스템과 상호작용할 수 있게 돼요. 다음 예시 요청으로 기능을 살펴보세요.

파일 관리 예시

  • "시를 하나 써서 내 바탕화면에 저장해 줘" — Claude가 시를 짓고 바탕화면에 새 텍스트 파일을 만들어요
  • "내 다운로드 폴더에 업무 관련 파일이 뭐가 있어?" — Claude가 다운로드 폴더를 훑어 업무 관련 문서를 찾아줘요
  • "내 바탕화면에 있는 모든 이미지를 'Images'라는 새 폴더로 정리해 줘" — Claude가 폴더를 만들고 이미지 파일을 그 안으로 옮겨요

승인 방식 (How Approval Works)

파일 시스템 작업을 실행하기 전에 Claude는 반드시 여러분의 승인을 요청해요. 모든 동작에 대한 통제권을 갖도록 보장해 주는 장치죠. 승인하기 전에 각 요청을 꼼꼼히 검토하고, 제안된 동작이 마음에 들지 않으면 언제든 거부할 수 있어요.

문제 해결 (Troubleshooting)

설정이나 사용 중 문제가 생기면 아래 해결책이 흔한 문제를 다뤄줘요.

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

  1. Claude Desktop 완전히 다시 시작
  2. claude_desktop_config.json 파일 문법 확인
  3. claude_desktop_config.json에 포함된 파일 경로가 유효하고, 상대 경로가 아닌 절대 경로인지 확인
  4. 로그를 확인해 서버가 연결되지 않는 이유 파악
  5. 명령줄에서 서버를 직접 실행해 오류가 나는지 확인(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 Desktop에서 로그 가져오기

MCP 관련 Claude.app 로깅은 다음 위치의 로그 파일로 기록돼요.

  • macOS: ~/Library/Logs/Claude
  • Windows: %APPDATA%\Claude\logs
  • mcp.log — MCP 연결 및 연결 실패에 대한 일반 로깅 포함
  • mcp-server-SERVERNAME.log — 해당 서버의 stderr 출력 포함. Stdio 서버는 모든 로깅에 stderr를 사용할 수 있으므로, 이 파일이 오류만 담는 건 아니에요

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

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 다시 시작

아무것도 안 돼요. 어떻게 해야 하죠?

더 나은 디버깅 도구와 상세한 안내는 debugging 가이드를 참고하세요.

Windows 경로의 ENOENT 오류와 ${APPDATA}

구성한 서버가 로드에 실패하고, 로그에 경로 내 ${APPDATA} 관련 오류가 보인다면 %APPDATA%의 확장된 값을 claude_desktop_config.json의 env 키에 추가해야 할 수 있어요.

{
  "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

다음 단계 (Next Steps)

Claude Desktop을 로컬 MCP 서버에 성공적으로 연결했으니, 이제 설정을 확장할 수 있는 옵션들을 살펴보세요.