로컬 MCP 서버 연결하기

원문: https://modelcontextprotocol.io/docs/develop/connect-local-servers

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

이 가이드는 Claude Desktop을 예로 들어 로컬 MCP 서버에 연결하는 방법을 설명합니다. 여기서 다루는 개념은 다른 MCP 호환 클라이언트에도 동일하게 적용됩니다. 튜토리얼을 마치면 Claude는 사용자의 승인 하에 파일을 읽고, 문서를 만들고, 폴더를 정리하고, 파일 시스템을 검색할 수 있게 됩니다.

사전 준비

Claude Desktop

운영체제에 맞는 Claude Desktop을 설치하세요. macOS와 Windows를 모두 지원합니다.

이미 설치했다면 Claude 메뉴에서 "Check for Updates..."를 눌러 최신 버전인지 확인하세요.

Node.js

Filesystem Server를 포함한 많은 MCP 서버는 Node.js가 필요합니다. 터미널(또는 명령 프롬프트)에서 다음 명령으로 설치 여부를 확인하세요.

node --version

Node.js가 없다면 nodejs.org에서 설치하세요. 안정성을 위해 LTS 버전을 권장합니다.

MCP 서버 이해하기

MCP 서버는 표준화된 프로토콜로 Claude Desktop에 특정 기능을 제공하는 프로그램입니다. 각 서버는 Claude가 호출할 수 있는 도구를 노출하며, 모든 동작은 사용자 승인 후 실행됩니다.

Filesystem Server가 제공하는 도구 예시는 다음과 같습니다.

파일 내용과 디렉터리 구조 읽기
새 파일과 폴더 생성
파일 이동 및 이름 변경
파일 이름/내용 검색

Filesystem Server 설치

핵심은 Claude Desktop이 실행될 때 Filesystem Server를 자동으로 시작하도록 설정하는 것입니다. 이를 위해 설정 JSON 파일에 서버 실행 방법과 연결 정보를 기록합니다.

1) Claude Desktop 설정 열기

시스템 메뉴 바의 Claude 메뉴(앱 내부 설정이 아니라 시스템 메뉴)를 열고 "Settings..."를 선택합니다.

2) Developer 설정으로 이동

Settings 창의 좌측 사이드바에서 "Developer" 탭을 선택한 뒤 "Edit Config" 버튼을 클릭합니다.

이 작업은 설정 파일이 없으면 새로 만들고, 있으면 기존 파일을 엽니다. 파일 위치는 다음과 같습니다.

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

3) Filesystem Server 설정

설정 파일 내용을 아래 JSON 구조로 교체합니다.

{
  "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: 서버 패키지 이름
나머지 인자: 서버가 접근 가능한 디렉터리

보안 주의

Claude가 읽고 수정해도 괜찮은 디렉터리만 허용하세요. 서버는 사용자 계정 권한으로 실행됩니다.

4) Claude Desktop 재시작

설정 파일을 저장한 후 Claude Desktop을 완전히 종료하고 재시작합니다. 그러면 입력창 우측 하단에 MCP 서버 표시가 나타납니다. MCP 서버 표시 아이콘

이 표시를 클릭하면 Filesystem Server가 제공하는 도구를 확인할 수 있습니다.

표시가 보이지 않으면 아래 문제 해결을 참고하세요.

Filesystem Server 사용하기

연결 후에는 다음과 같은 요청을 실행할 수 있습니다.

파일 관리 예시

"바탕화면에 시를 써서 저장해줘" – 새 텍스트 파일 생성
"다운로드 폴더의 업무 관련 파일을 알려줘" – 다운로드 스캔
"바탕화면의 이미지를 Images 폴더로 정리해줘" – 파일 이동

승인 방식

모든 파일 작업은 실행 전에 승인이 필요합니다. 이를 통해 사용자는 모든 동작을 통제할 수 있습니다.

문제 해결

서버가 보이지 않음 / 해머 아이콘 없음

Claude Desktop을 완전히 재시작
claude_desktop_config.json 문법 확인
설정 파일의 경로가 절대 경로인지 확인
로그를 확인해 연결 실패 원인 파악
명령줄에서 서버를 직접 실행해 오류 확인

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 관련 로그는 다음 위치에 기록됩니다.

macOS: ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs\mcp*.log

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

Claude 로그에서 오류 확인
서버가 정상 빌드/실행되는지 확인
Claude Desktop 재시작

아무 것도 동작하지 않는다면?

더 자세한 디버깅은 디버깅 가이드를 참고하세요.

Windows에서 ${APPDATA} 경로 관련 ENOENT 오류

로그에 ${APPDATA} 경로가 그대로 남아 ENOENT 오류가 발생하는 경우, 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이 전역으로 설치되어 있어야 합니다

npx 명령이 계속 실패한다면 npm이 전역 설치되어 있는지 확인하세요. 전역 설치가 되어 있다면 %APPDATA%\npm 경로가 존재합니다. 없다면 다음 명령으로 설치할 수 있습니다.

npm install -g npm