2025년 3월 26일

MCP 사용 시작하기 가이드

MCP(Model Context Protocol)는 Claude와 같은 AI 어시스턴트가 외부 서비스 및 데이터와 안전하게 연결할 수 있게 해주는 오픈 프로토콜입니다. 일반적으로 Claude나 ChatGPT 같은 대형 언어 모델(LLM)은 사용자의 데이터나 앱과 완전히 분리되어 있지만, MCP를 통해 이 한계를 극복할 수 있습니다.

MCP란?

MCP는 AI 애플리케이션이 외부 데이터 및 서비스와 상호작용하는 방법을 표준화합니다. Gmail, Reddit, Instacart 같은 인터넷 서비스와 AI 앱이 통신할 수 있는 새로운 언어라고 생각하면 됩니다. Claude가 Google Drive 정리, 일정 관리, 쇼핑 주문 등의 실용적인 작업을 수행하는 데 MCP가 필요합니다.

시작하기

1. Claude Desktop 다운로드 및 데스크톱용 Claude 설치하기

MCP를 활용하기 위한 첫 단계는 MCP 호환 애플리케이션을 다운로드하는 것입니다. Claude Desktop(macOS와 Windows용)이 MCP와 호환되는 첫 번째 앱입니다. 다른 호환 앱으로는 Sage(macOS, iOS, iPadOS용), Cursor(AI 코드 에디터), Goose(Block에서 출시한 오픈소스 에이전트) 등이 있습니다.

Claude 데스크톱 앱은 Claude의 기능을 직접 컴퓨터로 가져와 워크플로우와 원활하게 통합할 수 있게 해줍니다.

시스템 요구 사항

macOS: macOS 11 (Big Sur) 이상
Windows: Windows 10 이상

설치 단계

Claude 다운로드 페이지를 방문하세요.
운영 체제에 맞는 버전을 선택하세요:
- Mac 사용자: “macOS” 클릭
- Windows 사용자: “Windows” 클릭

다운로드가 완료되면:

파일을 열어 설치를 완료하세요.
응용 프로그램 폴더(Mac) 또는 시작 메뉴(Windows)에서 Claude를 실행하세요.
계정으로 로그인하여 시작하세요.

2. npx와 uvx 설정하기

MCP(Model Context Protocol)에서 npx와 uvx를 설정해야 하는 이유

MCP(Model Context Protocol)에서 npx와 uvx를 설정해야 하는 이유는 MCP 서버를 로컬에서 실행하기 위해서입니다.
MCP 서버는 주로 “로컬”에서 동작하도록 설계되어 있습니다. 즉, 서버의 소스 코드를 다운로드하여 사용자의 컴퓨터에서 직접 실행합니다. 이 과정에서 npx와 uvx라는 명령줄 도구가 필요합니다:
– npx: Node.js 패키지 실행 도구로, npm(Node Package Manager)과 함께 제공됩니다. MCP 서버 중 많은 부분이 JavaScript/Node.js로 작성되어 있어 이를 실행하기 위해 필요합니다.
– uvx: UV(Ultraviolet) 패키지 관리자의 실행 도구로, Python 패키지 관리에 사용됩니다. 일부 MCP 서버는 Python으로 작성되어 있어 이를 실행하기 위해 필요합니다.
실제로 MCP 서버는 두 가지 주요 통신 메커니즘을 사용합니다:
– stdio (표준 입출력, Standard Input/Output library의 줄인말 같음): 기본적인 로컬 통신 방식으로, 대부분의 MCP 서버가 이 방식을 사용합니다. 이를 위해 npx나 uvx로 서버를 로컬에서 실행해야 합니다.
– SSE (Server-Sent Events): 인터넷을 통한 통신 방식으로, 일부 MCP 서버만 지원합니다. 이 방식을 사용하면 소스 코드를 다운로드할 필요 없이 URL을 통해 서버에 연결할 수 있지만, 아직 널리 지원되지 않습니다.

결론적으로, 현재 MCP 생태계에서는 대부분의 서버가 stdio 방식을 사용하기 때문에, 이러한 서버를 로컬에서 실행하기 위해 npx와 uvx 같은 패키지 실행 도구를 설정해야 합니다. 이는 MCP가 아직 발전 중인 기술이기 때문에, 향후 SSE 방식이 더 보편화되면 이러한 로컬 설정의 필요성이 줄어들 수 있습니다.

Windows에서 MCP 요구사항 설정하기

1. 관리자 권한으로 PowerShell 열기(참고 : CMD(DOS 프롬프트)로 하셔도 됩니다)

시작 메뉴에서: Windows 키를 누르고 “PowerShell”을 검색한 다음, “Windows PowerShell”을 마우스 오른쪽 버튼으로 클릭하여 “관리자 권한으로 실행”을 선택합니다.
또는 단축키 사용: Windows 키 + X를 누른 다음, 나타나는 메뉴에서 “Windows Terminal(관리자)” 또는 “PowerShell(관리자)”를 선택합니다.

2. Node.js 설치하기

winget install OpenJS.NodeJS.LTS

설치가 진행되는 동안 기다려주세요. 중간에 동의를 요청하는 메시지가 나타나면 ‘Y’를 입력하고 Enter를 누릅니다.

설치가 완료되면 PowerShell 창을 닫고 새로운 PowerShell 창을 관리자 권한으로 다시 엽니다. 이는 환경 변수를 새로 불러오기 위해 필요합니다.(권리자 권한으로 실행을 2~3 번 반복해보고 만약 명령어가 인식되지 않는다면, 컴퓨터를 재부팅하고 다시 시도해 보세요.)

3. 실행 정책 설정하기

새 PowerShell 창에 다음 명령어를 입력합니다

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

^{[Tip] PowerShell에서 Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned 을 실행하면 실행이 안되고 다시 입력하라고 나옵니다. 그래서 다시 넣고 엔터를 해도 변화가 없는 경우, 이처럼 명령어가 실행된 것 같지만 아무런 메시지가 표시되지 않는 상황을 걲을 수 있습니다. 이는 실제로 명령이 성공적으로 실행되었을 가능성이 높습니다. Windows PowerShell은 때로 작업이 성공적으로 완료되면 아무런 출력을 표시하지 않을 수 있습니다. 실행 정책이 올바르게 설정되었는지 확인하려면 다음 명령어를 입력해보세요: “Get-ExecutionPolicy -Scope CurrentUser” 이 명령어를 실행하면 현재 사용자에 대한 실행 정책 설정이 표시됩니다. “RemoteSigned”라고 표시된다면 정상적으로 설정된 것입니다}

“실행 정책을 변경하시겠습니까?” 메시지가 나타나면 ‘Y’를 입력하고 Enter를 누릅니다.
이 단계는 PowerShell이 다운로드한 스크립트를 실행할 수 있도록 허용합니다.

4. uv(uvx 사용을 위한) 설치하기

PowerShell 에서 다음 명령어를 입력합니다

winget install --id=astral-sh.uv -e

설치가 완료될 때까지 기다립니다.
설치가 완료되면 다시 PowerShell 창을 닫고 새로운 PowerShell 창을 엽니다.

5. 설치 확인하기

각 도구가 제대로 설치되었는지 확인하기 위해 다음 명령어들을 하나씩 실행해 봅니다:

Node.js 확인

node --version

버전 번호(예: v18.12.0)가 표시되어야 합니다.

npm(npx용) 확인:

npm --version

버전 번호(예: 8.19.2)가 표시되어야 합니다.

uv 확인

uv --version

버전 번호(예: 0.5.13)가 표시되어야 합니다.

문제 해결

만약 명령어가 인식되지 않는다면, 컴퓨터를 재부팅하고 다시 시도해 보세요.
그래도 문제가 있다면, 환경 변수 PATH에 다음 경로들이 추가되었는지 확인하세요:
- Node.js: C:\Program Files\nodejs
- uv: 일반적으로 %USERPROFILE%.uv\bin 또는 비슷한 경로

이제 npx와 uvx를 사용하여 MCP 서버를 실행할 준비가 되었습니다. MCP 클라이언트(Claude Desktop 등)에서 외부 서비스와 연결하는 데 이 도구들을 사용하게 됩니다.

macOS 설정하는 방법은 아래와 같습니다.

Terminal 앱 열기
Node.js 설치 확인: node --version 명령어 실행
설치되지 않았다면 Node.js 다운로드 및 설치
마찬가지로 uv 설치 확인: uv --version 명령어 실행
필요시 설치: 제공된 링크를 통해 다운로드

3. 활용할 MCP 사용 사례 찾기

PulseMCP의 사용 사례 쇼케이스( https://www.pulsemcp.com/use-cases )를 방문하여 일상생활이나 업무에 도움이 될 수 있는 사용 사례를 찾을 수 있습니다.

예를 들어:

4. MCP 프로그램 설치 및 사용

사용 사례 레시피 따라하기

각 서버와 AI 앱은 조금씩 다르게 작동하므로, 사용 사례 레시피의 상세 지침을 따라 서버-앱 조합이 어떻게 작동하는지 이해해야 합니다. 한 번 지침을 따라한 후에는 지속적으로 서버를 활용하는 방법을 이해할 수 있게 됩니다.

문제 해결(Trouble Shooting)

앱 설정을 불러 올 수 없습니다

Shrimp Task Manager MCP 서버를 claude desktop에 설치하면 직면했던 에러 메세지입니다. 다양한 해결책을 찾아 시도해보던 중 아래의 에러 메세지에서 답을 찾을 수 있었습니다. “mcpS”… is not valid JSON에서 mcpS는 filesystem MCP 서버 관련 에러라는 사실을 발견하였습니다. filesystem MCP 서버 설정을 claude_desktop_config.json 파일에서 지웠는데 문제가 반복되었습니다.

해결책

Claude Desktop 완전 삭제 및 재설치하여 해결할 수 있었습니다. localappdata폴더 밑에 Claude 폴더 삭제를 한 것이 유효했던 것으로 판단합니다. 3단계: 레지스트리 정리 (선택사항)는 정리할 레지스트리가 없었습니다.

Claude Desktop 완전 삭제 및 재설치 가이드

1단계: Claude Desktop 프로그램 삭제

방법 1: 제어판을 통한 삭제

Windows 설정 → 앱 → 설치된 앱
“Claude” 검색 후 제거 클릭
삭제 과정 완료

방법 2: 프로그램 추가/제거

제어판 → 프로그램 → 프로그램 및 기능
“Claude” 찾아서 제거 클릭

2단계: 사용자 데이터 및 설정 파일 삭제

삭제해야 할 폴더들:

C:\Users\[사용자명]\AppData\Roaming\Claude
C:\Users\[사용자명]\AppData\Local\Claude
C:\Users\[사용자명]\AppData\Local\Temp\Claude (있다면)

삭제 방법:

Windows + R → %appdata% 입력 → Enter
Claude 폴더 삭제
Windows + R → %localappdata% 입력 → Enter
Claude 폴더 삭제 (있다면)

3단계: 레지스트리 정리 (선택사항)

⚠️ 주의: 레지스트리 편집은 신중하게 진행하세요.

Windows + R → regedit 입력 → Enter
다음 경로에서 Claude 관련 항목 검색 및 삭제:
- HKEY_CURRENT_USER\Software\Claude
- HKEY_LOCAL_MACHINE\SOFTWARE\Claude

4단계: 시스템 재부팅

완전한 정리를 위해 컴퓨터 재시작

5단계: Claude Desktop 재설치

공식 다운로드: https://claude.ai/download
최신 버전 다운로드 및 설치
설치 완료 후 실행

6단계: 새로운 설정 파일 생성

설치 후 다음 위치에 새로운 설정 파일 생성:

C:\Users\[사용자명]\AppData\Roaming\Claude\claude_desktop_config.json

새 설정 파일 내용:

json{
  "mcpServers": {
    "mcp-shrimp-task-manager": {
      "command": "npx",
      "args": ["-y", "@cjo4m06/mcp-shrimp-task-manager@latest"],
      "env": {
        "DATA_DIR": "C:\\Users\\Asus\\Documents\\Shrimp-Task-Manager"
      }
    }
  }
}

CMD를 통한 빠른 폴더 접근:

cmd# AppData\Roaming 폴더 열기
explorer %appdata%

# AppData\Local 폴더 열기  
explorer %localappdata%

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

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

윈도우

npx -y @modelcontextprotocol/server-filesystem D:\

아래와 같이 표시되면 정상입니다. 위에서 “D:\’는 claude_desktop_config.json에서 server-filesystem MCP로 파일을 읽기, 쓰기등을 하도록 설정한 경로입니다.

C:\Users\Asus>npx -y @modelcontextprotocol/server-filesystem D:\
Secure MCP Filesystem Server running on stdio
Allowed directories: [ 'D:\\' ]

이 메시지는 Model Context Protocol(MCP) 파일시스템 서버가 성공적으로 실행되었다는 알림입니다. 구체적으로 설명하자면:

“Secure MCP Filesystem Server running on stdio” – 보안이 적용된 MCP 파일시스템 서버가 stdio(표준 입출력) 채널을 통해 실행 중임을 나타냅니다.
“Allowed directories: [ ‘D:\’ ]” – 이 서버가 ‘D:\’ 디렉토리(D 드라이브의 루트 폴더)에 대한 접근만 허용하도록 설정되었음을 의미합니다.

이 메시지는 npx 명령어로 MCP 파일시스템 서버를 실행했을 때 나타나는 성공 메시지입니다. 이 서버는 AI 모델(Claude와 같은)이 여러분 컴퓨터의 D 드라이브에 있는 파일들에 접근할 수 있도록 중개 역할을 합니다.

3~4시간이 걸려서 우연히 해결하였습니다. 데스크톱용 Claude을 닫았다 재실행하는 것만으로는 안 되는 경우, 꼭, 작업 관리자에서 Claude 애플리케이션을 완전히 종료하고 다시 시작하니 망치 모양이 보입니다.

원인은 다음과 같은 이유였을 가능성이 높습니다:

애플리케이션 캐시 문제: Claude 애플리케이션이 설정 파일의 변경사항을 감지하지 못하고 이전 캐시된 설정을 사용하고 있었을 수 있습니다.
프로세스 연결 문제: 애플리케이션이 실행 중일 때 MCP 서버를 시작했기 때문에, 이미 실행 중인 Claude 프로세스가 새로운 MCP 서버를 인식하지 못했을 수 있습니다.
리소스 초기화 필요: 애플리케이션이 MCP 관련 리소스와 연결을 처음 시작할 때만 초기화하고, 그 이후에는 변경사항을 자동으로 감지하지 않도록 설계되었을 수 있습니다.

이런 종류의 문제는 소프트웨어가 시작될 때 설정을 한 번 로드하고 실행 중에는 변경사항을 자동으로 감지하지 않는 경우에 흔히 발생합니다. 애플리케이션을 완전히 재시작함으로써 새로운 설정으로 모든 구성요소를 초기화할 수 있었던 것으로 보입니다.

앞으로 MCP 관련 설정을 변경할 때는 Claude 애플리케이션을 항상 완전히 재시작하는 것이 좋겠습니다.

Claude에서 데스크톱 로그 가져오기

MCP와 관련된 Claude.app 로깅은 다음 로그 파일에 기록됩니다.

맥 OS:~/Library/Logs/Claude
윈도우:%APPDATA%\Claude\logs.
mcp.logMCP 연결 및 연결 실패에 대한 일반적인 로깅이 포함됩니다.
지정된 파일에는 mcp-server-SERVERNAME.log지정된 서버의 오류(stderr) 로깅이 포함됩니다.

다음 명령을 실행하면 최근 로그를 나열하고 새로운 로그가 있으면 그에 따라 진행할 수 있습니다(Windows에서는 최근 로그만 표시합니다). cmd 창을 열고 아래의 명령을 실행하시거나 참고로 제 PC의 경우, C:\Users\Asus\AppData\Roaming\Claude\logs 폴더에 log 파일이 있는데, mcp*.log을 더블 클릭해도 메모장으로 열어서 볼 수 있습니다.

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

C:\Users\Asus\AppData\Roaming\Claude\logs 폴더 안에는 아래의 같이 mcp.log와 mcp-server-filesystem.log 2개의 log파일이 있습니다.

MCP 로그 파일 두 개의 역할과 차이는 다음과 같습니다:

mcp.log
- Model Context Protocol 클라이언트 측 로그입니다
- Claude 애플리케이션이 MCP 서버와 어떻게 통신하는지에 관한 정보를 기록합니다
- 연결 시도, 요청 전송, 응답 수신 등 클라이언트 측 활동을 추적합니다
- 문제가 발생했을 때 클라이언트 측 오류나 문제를 파악하는 데 유용합니다
mcp-server-filesystem.log
- MCP 파일시스템 서버 측 로그입니다. 즉 MCP server 로그입니다.
- 서버가 어떻게 동작하는지, 파일 시스템 액세스 요청을 어떻게 처리하는지에 관한 정보를 기록합니다
- 디렉토리 접근, 파일 읽기/쓰기 작업, 권한 문제 등을 추적합니다
- 서버 측에서 발생하는 오류나 문제를 디버깅하는 데 유용합니다

이 두 로그 파일은 함께 작동하여 MCP 시스템의 전체 흐름을 이해하는 데 도움이 됩니다. 클라이언트에서 서버로의 요청, 서버에서의 처리, 그리고 다시 클라이언트로의 응답까지의 전체 과정을 추적할 수 있습니다. 연결 문제나 파일 액세스 오류가 발생할 경우, 이 두 로그 파일을 함께 검토하면 문제의 원인을 보다 정확하게 파악할 수 있습니다.

도구 호출이 자동으로 실패함

클로드가 도구를 사용하려고 시도하지만 실패하면:

Claude의 로그에서 오류를 확인하세요.
서버가 오류 없이 빌드되고 실행되는지 확인하세요.
데스크탑용 Claude를 다시 시작해 보세요.

이 중 아무것도 작동하지 않습니다. 어떻게 해야 하나요?

더 나은 디버깅 도구와 자세한 지침은 디버깅 가이드 를 참조하세요 .

Windows에서 경로에 ENOENT 오류 및 `${APPDATA}`가 있음

구성된 서버가 로드되지 않고 해당 로그에서 경로 내부에 참조되는 오류가 표시되면 확장된 값을 키 에 ${APPDATA}추가해야 할 수 있습니다 .%APPDATA%envclaude_desktop_config.json

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
      "BRAVE_API_KEY": "..."
    }
  }
}

Windows 사용자: PYTHONUTF8=1 환경 변수 사용

Windows에서 MCP 서버를 사용할 때 Python이 UTF-8 인코딩을 사용하도록 이 환경 변수를 추가해야 할 수 있습니다.

서버 경로에서 공백 제거

Cursor와 함께 서버를 실행할 때 흔히 발생하는 문제입니다. 공백이 없는 경로로 서버를 이동하는 것이 간단한 해결책입니다(예: C:/my-projects/mcpserver/build/index.js 대신 C:/my-projects/mcpserver/build/index.js 사용).

MCP 생태계는 계속 발전하고 있으며, 시간이 지남에 따라 비기술적 사용자와 후발 도입자를 위해 이 프로세스가 더 쉬워질 것으로 예상됩니다.

Filesystem MCP Server 사용후기

조금은 실망 스럽습니다. 조금 더 시도해보고 추가 메모해보겠습니다.

“D:\Documents 에 있는 비용CMS.xls 파일을 읽고 TN-2360/2380/2700 재생토너의 가격이 얼마인지 알려주세요.”라고 물어보았습니다.
비용CMS.xls 파일의 크기는 2,397KB입니다.
10분이 지났는데 아직도 열심히 찾고 있습니다.
search_file과 read_file을 반복하고 있습니다.
사람이 한다면 경로를 찾고 파일을 찾고 파일을 열어 다시 TN-2360/2380/2700을 찾을 것 같은데 일일히 JavaScript로 프로그래밍을 하고 이것을 실행합니다.
아래는 다수의 JavaScript 중 일부입니다.
// Read the Excel file
const response = await window.fs.readFile(‘D:/Documents/비용CMS.xls’);
// Use SheetJS to parse the Excel file
import * as XLSX from ‘xlsx’;
// Parse the Excel file with full options
const workbook = XLSX.read(response, {
cellStyles: true,
cellFormulas: true,
cellDates: true,
cellNF: true,
sheetStubs: true
});
// List all sheets
console.log(“Sheets in workbook:”, workbook.SheetNames);
// Function to search for TN-2360/2380/2700 in a worksheet
function searchTonerInSheet(worksheet) {
const results = [];

// Convert sheet to JSON
const jsonData = XLSX.utils.sheet_to_json(worksheet, {header: 1, defval: ""});

// Search for relevant rows containing our toner models
jsonData.forEach((row, index) => {
    const rowStr = row.join(" ");
    if (rowStr.includes("TN-2360") || rowStr.includes("TN-2380") || rowStr.includes("TN-2700") || 
        rowStr.includes("TN2360") || rowStr.includes("TN2380") || rowStr.includes("TN2700")) {
        results.push({index: index, data: row});
    }
});

return results;

}
// Search in each sheet
for (const sheetName of workbook.SheetNames) {
console.log(\nSearching in sheet: ${sheetName});
const worksheet = workbook.Sheets[sheetName];
const results = searchTonerInSheet(worksheet);

if (results.length > 0) {
    console.log(`Found ${results.length} potential matches in sheet "${sheetName}":`);
    results.forEach(result => {
        console.log(`Row ${result.index + 1}:`, result.data);
    });
} else {
    console.log(`No matches found in sheet "${sheetName}"`);
}

}

참고자료 : 1. 데스크톱용 Claude 설치하기

2. How To Get Started Using MCP

상희 김

검색엔진최적화, 인바운드마케팅, 유튜브최적화 전문

Claude Desktop 앱, MCP 서버 설정 및 활용 가이드

상희 김

답글 남기기 응답 취소

Claude Desktop 앱, MCP 서버 설정 및 활용 가이드

MCP 사용 시작하기 가이드

MCP란?

시작하기

1. Claude Desktop 다운로드 및 데스크톱용 Claude 설치하기

시스템 요구 사항

설치 단계

2. npx와 uvx 설정하기

Windows에서 MCP 요구사항 설정하기

1. 관리자 권한으로 PowerShell 열기(참고 : CMD(DOS 프롬프트)로 하셔도 됩니다)

2. Node.js 설치하기

3. 실행 정책 설정하기

4. uv(uvx 사용을 위한) 설치하기

5. 설치 확인하기

문제 해결

macOS 설정하는 방법은 아래와 같습니다.

3. 활용할 MCP 사용 사례 찾기

4. MCP 프로그램 설치 및 사용

사용 사례 레시피 따라하기

문제 해결(Trouble Shooting)

앱 설정을 불러 올 수 없습니다

해결책

Claude Desktop 완전 삭제 및 재설치 가이드

1단계: Claude Desktop 프로그램 삭제

방법 1: 제어판을 통한 삭제

방법 2: 프로그램 추가/제거

2단계: 사용자 데이터 및 설정 파일 삭제

삭제해야 할 폴더들:

삭제 방법:

3단계: 레지스트리 정리 (선택사항)

4단계: 시스템 재부팅

5단계: Claude Desktop 재설치

6단계: 새로운 설정 파일 생성

새 설정 파일 내용:

CMD를 통한 빠른 폴더 접근:

Filesystem MCP Server 사용후기

상희 김

Related posts

퍼플렉시티 코멧 (Perplexity Comet) 이용 방법과 활용처

AGI급 AI 플랫폼 핵심 구성요소 및 영향 분석

LLM의 핵심 기술 : 임베딩 벡터(embedding vectors)와 어텐션 메커니즘

답글 남기기 응답 취소