로컬 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 메뉴를 클릭한 다음 "Check for Updates..."를 선택하여 최신 버전을 실행 중인지 확인해 주십시오.
Node.js
Filesystem Server를 비롯한 많은 다른 MCP 서버들은 실행을 위해 Node.js가 필요합니다. 터미널이나 명령 프롬프트를 열고 다음 명령을 실행하여 Node.js 설치 여부를 확인해 주십시오.
node --version
Node.js가 설치되어 있지 않은 경우, nodejs.org에서 다운로드해 주십시오. 안정성을 위해 LTS(장기 지원) 버전을 사용하는 것을 권장합니다.
MCP 서버 이해하기
MCP 서버는 사용자의 컴퓨터에서 실행되는 프로그램으로, 표준화된 프로토콜을 통해 Claude Desktop에 특정 기능들을 제공합니다. 각 서버는 사용자의 승인 하에 Claude가 작업을 수행하는 데 사용할 수 있는 도구들을 제공하며, 저희가 설치할 Filesystem Server는 다음과 같은 도구들을 제공합니다:
- 파일 내용 및 디렉터리 구조 읽기
- 새로운 파일 및 디렉터리 생성
- 파일 이동 및 이름 변경
- 파일명 또는 내용에 따른 파일 검색
모든 작업은 실행되기 전에 사용자의 명시적인 승인이 필요하므로, Claude가 접근하거나 수정할 수 있는 내용에 대해 완전한 통제권을 유지할 수 있습니다.
파일시스템 서버 설치하기
이 과정은 애플리케이션을 실행할 때마다 자동으로 파일시스템 서버를 시작하도록 Claude Desktop을 설정하는 것을 포함합니다. 이러한 설정은 Claude Desktop에 어떤 서버를 실행해야 하는지 및 그 서버들에 어떻게 연결해야 하는지를 지시하는 JSON 파일을 통해 이루어집니다.
Claude Desktop 설정 열기
먼저 Claude Desktop의 설정에 접근해야 합니다. 시스템 메뉴 바에 있는 Claude 메뉴( Claude 창 내부의 설정 메뉴가 아님)를 클릭한 다음 "Settings..."를 선택하십시오.
macOS의 경우 상단 메뉴 바에 다음과 같이 표시됩니다:
이렇게 하면 Claude 계정 설정과는 별개인 Claude Desktop 설정 창이 열립니다.
개발자 설정 접근하기
설정 창에서 왼쪽 사이드바에 있는 "Developer" 탭으로 이동하십시오. 이 섹션에는 MCP 서버 및 기타 개발자 관련 기능을 설정할 수 있는 옵션이 포함되어 있습니다.
설정 파일을 열려면 "Edit Config" 버튼을 클릭하십시오:
이 작업은 현재 구성 파일이 존재하지 않을 경우 새로운 구성 파일을 생성하거나, 기존에 있는 구성 파일을 엽니다. 해당 파일의 위치는 다음과 같습니다:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
파일시스템 서버 설정
구성 파일의 내용을 다음 JSON 구조로 대체해 주십시오. 이 설정을 통해 Claude Desktop은 특정 디렉터리에 대한 접근 권한을 가지고 파일시스템 서버를 시작하도록 지시받습니다:
{
"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 배열에 명시된 경로들은 파일시스템 서버가 접근할 수 있는 디렉터리를 나타냅니다. 필요에 따라 이러한 경로들을 수정하거나 추가적인 디렉터리를 포함시킬 수 있습니다.
Claude Desktop 재시작
구성 파일을 저장한 후에는 Claude Desktop을 완전히 종료한 다음 다시 시작해 주십시오. 새로운 구성을 로드하고 MCP 서버를 시작하려면 애플리케이션을 재시작해야 합니다.
성공적으로 재시작되면 대화 입력 상자의 왼쪽 하단에 위치한 "파일, 커넥터 및 기타 항목 추가 /" 표시기 
를 클릭하십시오:
이 표시기를 클릭한 다음 마우스를 "커넥터" 위로 옮겨 "커넥터 관리"를 클릭하십시오. 커넥터 목록에서 "filesystem"을 선택하여 Filesystem Server에서 사용할 수 있는 도구들을 확인할 수 있습니다:
Filesystem Server가 연결되지 않는 경우, 디버깅 단계를 확인하려면 문제 해결 섹션을 참조하십시오.
Filesystem Server 사용 방법
파일시스템 서버에 연결되면 Claude는 이제 사용자의 파일시스템과 상호작용할 수 있습니다. 해당 기능들을 확인해 보려면 다음 예제 요청들을 시도해 보십시오.
파일 관리 예제
- "시를 써서 제 데스크톱에 저장해 주실 수 있나요?" - Claude는 시를 작성한 후 사용자의 데스크톱에 새로운 텍스트 파일을 생성합니다.
- "제 다운로드 폴더에는 어떤 업무 관련 파일들이 있나요?" - Claude는 다운로드 폴더를 스캔하여 업무 관련 문서들을 찾아냅니다.
- "제 데스크톱에 있는 모든 이미지 파일들을 ‘Images’라는 새로운 폴더로 정리해 주세요" - Claude는 해당 폴더를 생성한 뒤 이미지 파일들을 그 안으로 이동시킵니다.
승인 작동 방식
어떠한 파일시스템 작업을 실행하기 전에 Claude는 반드시 사용자의 승인을 요청합니다. 이를 통해 모든 작업에 대한 통제권을 사용자가 유지할 수 있습니다.
승인을 하기 전에 각 요청을 주의 깊게 검토해 주십시오. 제안된 작업이 마음에 들지 않을 경우 언제든지 요청을 거절할 수 있습니다.
문제 해결
Filesystem Server를 설정하거나 사용하는 과정에서 문제가 발생할 경우, 다음의 해결 방법들은 자주 나타나는 문제들을 다룹니다.
Claude에 서버가 표시되지 않거나 해머 아이콘이 사라짐
- Claude Desktop을 완전히 재시작합니다.
claude_desktop_config.json파일의 구문을 확인합니다.claude_desktop_config.json에 포함된 파일 경로가 유효하며 상대 경로가 아닌 절대 경로인지 반드시 확인합니다.- 서버가 연결되지 않는 이유를 알아보기 위해 logs를 살펴봅니다.
- 명령줄에서
username을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 로그 확인
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을 재시작해 보세요.
위의 방법들 모두 효과가 없습니다. 어떻게 해야 하나요?
보다 우수한 디버깅 도구와 보다 상세한 안내를 원하신다면 저희의 디버깅 가이드를 참조해 주시기 바랍니다.
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을 다시 시작해 주십시오.
다음 단계
이제 Claude Desktop을 로컬 MCP 서버에 성공적으로 연결했으니, 설정을 더욱 확장하기 위해 다음 옵션들을 살펴보시기 바랍니다.