홈 / AI활용 / Claude Desktop + MCP 완벽 가이드 - 초보 개발자를 위한 시작부터 활용까지 (macOS)
ChatGPT가 한 참이나 일반인들에게 까지 확장되어 사용하고 있을 때, 갑자기 AI 코딩에 특화된(?) Cursor 개발 환경 플랫폼 및 Claud 생성형 AI서비스를 접하게 됩니다. AI코딩에 특화되어 있다보니, 다른 어플리케이션과의 연계성도 고려할 수 밖에 없고 MCP라는 프로토콜을 활용한 개발도 지원하게 됩니다.
쉽게 말해서 MCP는 나 혼자만 일 잘하는게 아니라 다른 프로그램에 일을 시키는 일을 잘하게 되는거죠.
특히나 프로젝트 기획 및 디자인에 전문적인 Figma와의 연결은 IT프로젝트의 팀원간 협업에 극적인 생산성과 협업 매커니즘을 만들기 시작했습니다.
1. Claude Desktop 개요 : 브라우저 버전과의 차이점
Claude Desktop은 Anthropic에서 출시한 데스크톱 애플리케이션으로, 웹 브라우저 버전과는 차별화된 기능을 제공합니다. 가장 큰 차이점은 Model Context Protocol(MCP)를 통한 외부 시스템 연동이 가능하다는 점입니다.
브라우저 버전이 단순히 텍스트 기반 대화만을 지원한다면, 데스크톱 버전은 로컬 파일 시스템, 데이터베이스, API 등 다양한 외부 리소스에 직접 접근할 수 있습니다. 또한 로컬 환경에서 실행되므로 보안 측면에서도 더욱 안전하며, 개발자들이 필요로 하는 고급 기능들을 제공합니다.
2. Claude Desktop 설치 및 설정
Download Claude
Download Claude for your desktop or mobile device.
claude.ai
- Claude Desktop 설치는 매우 간단합니다. 공식 웹사이트(https://claude.ai/download)에서 macOS 또는 Windows용 설치 파일을 다운로드할 수 있으며, Linux는 아직 지원되지 않습니다.
- 설치 후에는 Claude 메뉴에서 "Check for Updates..."를 선택하여 최신 버전으로 업데이트하는 것이 중요합니다.
- 설치가 완료되면 Settings → Developer → Edit Config를 통해 MCP 서버 설정을 구성할 수 있습니다.
- 이 설정 파일은 ~/Library/Application Support/Claude/claude_desktop_config.json 경로에 저장되며, 다양한 MCP 서버들을 연결하는 핵심적인 역할을 합니다.
3. MCP 사용을 위한 사전 준비사항
Claude Desktop에서 MCP 기능을 원활하게 사용하기 위해서는 몇 가지 사전 준비가 필요합니다.
Node.js 설치
Node.js — Run JavaScript Everywhere
Node.js® is a free, open-source, cross-platform JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.
nodejs.org
가장 중요한 것은 Node.js 설치입니다. 대부분의 MCP 서버가 npx 명령을 통해 실행되기 때문에 Node.js는 필수 요소입니다. 공식 웹사이트(https://nodejs.org)에서 LTS 버전을 다운로드하여 설치합니다. 터미널에서 node --version과 npm --version 명령으로 정상 설치를 확인할 수 있습니다.
# 설치 확인
node --version
v22.17.0
npm --version
10.9.2
# 설치되지 않은 경우
# https://nodejs.org 에서 LTS 버전 다운로드
Python과 uv패키지 설치 : Python기반 MCP 서버 사용 시
Python 기반 MCP 서버를 사용할 경우에는 Python 3과 uv 패키지 매니저도 설치해야 합니다. Python을 설치하는 방법은 이미 설치되었거나, 다른 곳에서 많이 안내하고 있으므로 참고하시면 될듯하고, uv는 curl -LsSf https://astral.sh/uv/install.sh | sh 명령으로 간단하게 설치할 수 있습니다.
# 설치 확인
python3 --version
# uv 설치 (권장)
curl -LsSf https://astral.sh/uv/install.sh | sh
선택적 설치 항목 : Docker와 Git
Docker (컨테이너 기반 MCP 서버 사용 시)
# Docker Desktop 설치
# https://docs.docker.com/desktop/install/mac/
2. Git (GitHub MCP 서버 등 사용 시)
# 설치 확인
git --version
# Xcode Command Line Tools와 함께 설치됨
xcode-select --install
API 키 및 토큰 준비
API 키와 토큰 준비도 중요한 사전 작업입니다.
- GitHub MCP 서버를 사용하려면 GitHub Personal Access Token을 발급받아야 하며, 이는 GitHub의 Settings → Developer settings에서 생성할 수 있습니다.
- Google 서비스(Gmail, Drive 등)를 연동하려면 Google Cloud Console에서 프로젝트를 생성하고 해당 API(Google API, Drive API)를 활성화한 후 OAuth 2.0 클라이언트 ID를 생성해야 합니다.
- 기타 서비스별로도 각각의 API 키가 필요하므로, 사용하고자 하는 서비스의 공식 문서를 참고하여 미리 준비하는 것이 좋습니다.
시스템 권한 설정
시스템 권한 설정도 놓치기 쉬운 중요한 부분입니다.
- macOS의 경우 시스템 환경설정 → 보안 및 개인정보보호 → 파일 및 폴더에서 Claude Desktop에 필요한 폴더 접근 권한을 부여해야 합니다.
- Filesystem MCP Extensions : Claude Desktop > Setting > Extensions > Filesystem에서 특정 폴더를 지정하여 시스템 설정 변경없이도 폴더에 접근 할 수도 있습니다. - 추가설치 필요 없음)
- 또한 환경 변수 설정을 위해 ~/.zshrc 파일을 편집하여 API 키들을 안전하게 관리할 수 있습니다. 예를 들어 export GITHUB_PERSONAL_ACCESS_TOKEN="your_token_here"와 같은 형태로 설정하면, 설정 파일에 직접 토큰을 노출하지 않고도 MCP 서버에서 사용할 수 있습니다.
# API 키들을 환경 변수로 설정
export GITHUB_PERSONAL_ACCESS_TOKEN="your_token_here"
export OPENAI_API_KEY="your_key_here"
# 등등...
Claude Desktop 설정 파일 위치 확인
# Claude Desktop 설정 파일 위치
~/Library/Application\ Support/Claude/claude_desktop_config.json
4. Claude Desktop GUI에서 MCP 설정하기
Claude Desktop에서 MCP 서버를 설정하는 과정은 GUI를 통해 비교적 간단하게 수행할 수 있습니다.
설정 파일 열기
- Claude Desktop > Settings > Developer > Edit Config > 'claude_desktop_config.json'
- 첫 번째 단계는 Claude Desktop을 실행한 후 화면 상단의 메뉴바에서 "Claude" 메뉴를 클릭하는 것입니다. 여기서 주의할 점은 앱 창 내부의 설정이 아닌, macOS 메뉴바의 Claude 메뉴를 선택해야 한다는 것입니다.
- 메뉴가 열리면 "Settings..."를 클릭하여 설정 창을 엽니다. 이 과정에서 혼동을 피하기 위해 앱 창 내부의 설정 버튼과 메뉴바의 Claude 메뉴를 구분하는 것이 중요합니다.
- 설정 창이 열리면 왼쪽 사이드바에서 "Developer" 항목을 클릭합니다. 이 섹션은 개발자 전용 기능들을 모아놓은 곳으로, MCP 서버 설정 외에도 다양한 고급 기능들을 제공합니다.
- Developer 섹션을 선택하면 오른쪽에 "Edit Config" 버튼이 나타나며, 이 버튼을 클릭하면 텍스트 에디터에서 설정 파일이 열립니다. 만약 설정 파일이 존재하지 않는다면, Claude Desktop이 자동으로
- ~/Library/Application Support/Claude/claude_desktop_config.json 경로에 새 파일을 생성합니다.
설정 파일 편집
- JSON 설정 파일이 텍스트 에디터에서 열리면, MCP 서버 설정을 추가할 수 있습니다.
- 파일이 비어있다면 기본 구조부터 작성해야 하며, 이미 내용이 있다면 mcpServers 섹션에 새로운 서버를 추가합니다.
- JSON 문법을 정확히 지키는 것이 매우 중요하며, 중괄호, 쉼표, 따옴표 등이 빠지지 않도록 주의해야 합니다.
- 설정을 완료한 후에는 파일을 저장하고 텍스트 에디터를 종료합니다.
- 문법 오류가 있으면 Claude Desktop이 시작되지 않을 수 있으므로, JSON validator를 사용하여 문법을 검증하는 것을 권장합니다.
Claude Destop 다시 시작
- 설정 파일을 저장한 후에는 Claude Desktop을 완전히 종료하고 다시 시작해야 합니다.
- 단순히 창을 닫는 것이 아니라, Dock에서 Claude Desktop을 우클릭하여 "Quit"을 선택하거나, Command+Q를 눌러 완전히 종료시켜야 합니다.
- 재시작 후에는 MCP 서버가 정상적으로 연결되었는지 확인할 수 있습니다.
- 성공적으로 연결되었다면 대화 입력창의 왼쪽 하단에 슬라이더 형태의 아이콘이 나타납니다. 이 아이콘을 클릭하면 연결된 MCP 서버들과 사용 가능한 도구들의 목록을 확인할 수 있습니다.
5. MCP 서버 유형별 분류 및 추천
Claude MCP란 무엇인가?
Model Context Protocol(MCP)은 AI 어시스턴트와 데이터 소스 간의 안전하고 양방향적인 연결을 구축할 수 있게 해주는 개방형 표준입니다. 이 프로토콜을 통해 개발자들은 자신의 데이터를 MCP 서버로 노출시키거나, MCP 클라이언트가 되는 AI 애플리케이션을 구축할 수 있습니다. Claude Desktop은 MCP 클라이언트 역할을 하며, 다양한 MCP 서버들과 연결되어 외부 시스템의 데이터와 도구에 접근할 수 있습니다. 이는 기존의 파편화된 통합 방식을 단일 프로토콜로 대체하여, 개발자들이 더욱 효율적으로 AI 기반 애플리케이션을 구축할 수 있게 해줍니다.
Connector 유형 (데이터베이스 및 API 연결)
- Connector 유형의 MCP 서버는 기존 시스템과 API에 직접 연결하여 데이터를 가져오는 역할을 합니다.
- 주요 예시로는 PostgreSQL, MySQL, GitHub, Google Drive, Slack 등이 있으며, 이들은 각각의 API나 프로토콜을 통해 데이터에 접근합니다. 이 유형의 서버들은 일반적으로 인증 토큰이나 데이터베이스 연결 정보가 필요하며, 환경 변수를 통해 민감한 정보를 안전하게 관리합니다.
- 초보 개발자에게는 GitHub MCP 서버나 Google Drive MCP 서버부터 시작하는 것을 추천하며, 이들은 상대적으로 설정이 간단하고 사용법을 익히기 쉽습니다.
Extension 유형 (기능 확장)
- Extension 유형은 Claude Desktop의 기본 기능을 확장하는 역할을 합니다.
- Desktop Extensions(DXT)의 도입으로 로컬 MCP 서버의 설치와 관리가 훨씬 쉬워졌습니다.
- 이 유형의 서버들은 주로 개발 도구, 유틸리티, 또는 특정 작업을 자동화하는 기능들을 제공합니다. 예를 들어, 파일 시스템 접근, 웹 스크래핑, 이미지 처리 등의 기능을 제공하는 서버들이 이 범주에 속합니다.
- Extension 유형은 .dxt 파일 형태로 패키징되어 배포되며, Claude Desktop의 설정에서 직접 관리할 수 있습니다.
Custom 유형 (맞춤형 솔루션)
- Custom 유형은 개발자가 직접 만든 맞춤형 MCP 서버를 의미합니다.
- Claude 3.5 Sonnet은 MCP 서버 구현을 빠르게 구축하는 데 능숙하여, 조직과 개인이 가장 중요한 데이터셋과 다양한 AI 기반 도구를 신속하게 연결할 수 있게 해줍니다.
- Python, TypeScript, Java 등 다양한 언어로 개발할 수 있으며, 특정 비즈니스 로직이나 내부 시스템과의 연동이 필요한 경우에 활용됩니다.
- 초보 개발자라면 공식 SDK와 예제 코드를 참고하여 간단한 기능부터 시작하는 것이 좋습니다.
6. 실제 MCP 서버 연결
첫 번째 MCP 서버 연결 : Filesystem MCP 서버
초보자가 가장 쉽게 시작할 수 있는 MCP 서버는 Filesystem 서버입니다. 이 서버는 추가적인 API 키나 복잡한 설정 없이 바로 사용할 수 있어 MCP의 작동 원리를 이해하기에 적합합니다. 설정 파일에 다음과 같이 추가합니다.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/Users/username/Downloads"
]
}
}
}
- 여기서 username을 실제 사용자명으로 변경해야 하며, Claude가 접근할 수 있는 폴더 경로를 지정합니다.
- Desktop과 Downloads 폴더는 일반적으로 안전한 선택이지만, 필요에 따라 다른 경로를 추가할 수 있습니다.
- 설정 후 Claude Desktop을 재시작하면, "Desktop 폴더의 파일 목록을 보여줘" 또는 "Downloads 폴더에 새 텍스트 파일을 만들어줘"와 같은 명령을 통해 파일 시스템과 상호작용할 수 있습니다.
현재는 Claude Desktop에서 Local MCP Server로 간편하게 'Extensions'에서 추가할 수 있습니다.
Figma MCP 연결
공식 Figma Dev Mode MCP 서버를 먼저 시도해보세요.
이것이 가장 안정적이고 Figma에서 직접 지원하는 방법입니다. Figma Dev Mode MCP는 Claude Desktop Extentions에 기본적으로 내장되어 있습니다. 또한 Figma Desktop앱의 상단메뉴에서 Figma > Preferences > "Enalbel Dev Mode MCP Server"를 체크하셔서 Figma에서 Figma Dev Mode MCP를 활성화 해야 합니다.
이렇게 공식 Figma Dev Mode MCP를 설정하게 되면, 설정파일에서 아래와 같이 설정하는 것과 같은 효과입니다. (실제로 아래의 내용을 설정파일에 추가하실 필요는 없습니다. 또한 API Key도 연계된 Figma Desktop에 연결된 계정을 사용하므로 별도로 등록할 필요가 없습니다.)
{
"mcpServers": {
"figma-dev-mode": {
"command": "mcp",
"args": ["--transport", "sse", "http://localhost:3845/sse"]
}
}
}
Figma MCP 서버는 디자인 파일과 AI 간의 연결을 가능하게 합니다. 연결을 위해서는 먼저 Figma Personal Access Token을 발급받아야 하며, 이는 Figma 계정 설정에서 생성할 수 있습니다. 설정 파일에서 다음과 같이 구성합니다:
{
"mcpServers": {
"figma": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-figma"],
"env": {
"FIGMA_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
}
}
}
}
- 실제 활용 예시로는 Figma 디자인 파일에서 컴포넌트 정보를 추출하여 코드를 자동 생성하거나, 디자인 시스템의 일관성을 검증하는 작업 등이 있습니다.
- Claude Desktop에서 "Figma 파일의 버튼 컴포넌트를 분석하여 React 코드로 변환해줘"와 같은 요청을 하면, MCP 서버가 Figma API를 통해 디자인 정보를 가져와 분석한 후 해당하는 코드를 생성해줍니다.
- 현재는 Claude Desktop > Settings > Extension의 Local MCP server로 'Figma Dev Mode' 를 설정해서 손쉽게 사용할 수 있습니다. 위에서 언급된 Figma와 Figma Dev Mode를 동시에 설정하는 경우 'Figma disconnected' 에러 메시지를 만날 수도 있습니다.
MySQL 및 PostgreSQL 연결
데이터베이스 연결은 MCP의 가장 강력한 기능 중 하나입니다. PostgreSQL MCP 서버 설정은 다음과 같이 구성할 수 있습니다:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_URL": "postgresql://username:password@localhost:5432/database_name"
}
}
}
}
- MySQL의 경우에도 유사하게 설정할 수 있으며, MariaDB MCP 서버를 사용하여 연결할 수 있습니다.
- 실제 활용 예시로는 "지난 달 매출 데이터를 분석하여 트렌드를 시각화해줘"라는 요청을 Claude에게 하면, MCP 서버가 데이터베이스에 연결하여 SQL 쿼리를 실행하고, 결과 데이터를 분석하여 차트나 그래프로 시각화해줍니다.
- 또한 데이터의 이상치를 탐지하거나, 특정 조건에 맞는 레코드를 찾는 등의 복잡한 분석 작업도 자연어 명령만으로 수행할 수 있습니다.
Midjourney 프롬프트: database connection diagram, PostgreSQL and MySQL logos, secure connection lines, data flow visualization, modern tech illustration, blue and green colors --ar 16:9 --style raw 캡션: 데이터베이스 MCP 연동 아키텍처 시각화
Gmail 연결
Gmail MCP 서버는 이메일 관리를 자연어 명령으로 수행할 수 있게 해주는 강력한 도구입니다.
Gmail 연동을 위해서는 Google Cloud Console에서 OAuth 2.0 클라이언트 ID를 생성하고, Gmail API를 활성화해야 합니다. 설정 과정은 다음과 같습니다:
- 먼저 Google Cloud Console에서 새 프로젝트를 생성하고, Gmail API를 활성화합니다.
- OAuth 동의 화면을 구성한 후, OAuth 2.0 클라이언트 ID를 생성하여 credentials.json 파일을 다운로드합니다.
- 자동 인증을 지원하는 Gmail MCP 서버를 사용하면 설정이 더욱 간편해집니다.
- Claude Desktop 설정 파일에 다음과 같이 추가합니다:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": ["@gongrzhe/server-gmail-autoauth-mcp"]
}
}
}
- 실제 활용 예시로는 "지난 주에 받은 프로젝트 관련 이메일을 모두 찾아서 요약해줘"라고 요청하면, Gmail MCP 서버가 해당 조건에 맞는 이메일들을 검색하고 내용을 분석하여 핵심 포인트를 요약해줍니다.
- 또한 첨부파일 지원, 이메일 전송, 라벨 관리 등의 기능을 통해 이메일 워크플로우를 완전히 자동화할 수 있습니다. "긴급 표시가 있는 미읽음 이메일에 '확인완료' 라벨을 추가하고 회신 템플릿을 작성해줘"와 같은 복합적인 작업도 한 번의 명령으로 처리할 수 있습니다.
GitHub 연결 및 개발 워크플로우 통합
GitHub MCP 서버는 소스 코드 관리와 협업 워크플로우를 AI와 통합할 수 있게 해줍니다. GitHub Personal Access Token을 발급받은 후 다음과 같이 설정합니다:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
}
}
}
}
- 이를 통해 "최근 PR에서 코드 리뷰 코멘트를 요약해줘", "새로운 이슈를 생성하고 버그 리포트를 작성해줘", "특정 브랜치의 변경사항을 분석해줘" 등의 작업을 자연어로 수행할 수 있습니다.
- 특히 코드 검토, 이슈 관리, 프로젝트 문서화 등의 반복적인 작업들을 크게 효율화할 수 있습니다.
7. MCP 서버의 활용 및 주의사항
보안 및 주의사항
MCP 서버를 사용할 때는 보안에 특별히 주의해야 합니다. Claude Desktop은 사용자 계정 권한으로 설정 파일의 명령을 실행하며 로컬 파일에 접근하므로, 신뢰할 수 있는 소스의 명령만 추가해야 합니다. 특히 제3자가 개발한 MCP 서버를 사용할 때는 코드를 검토하고, 필요한 권한만 부여하는 것이 중요합니다.
환경 변수를 통해 API 키나 데이터베이스 연결 정보 등의 민감한 정보를 관리할 때는 .env 파일을 사용하거나, 시스템 환경 변수로 설정하여 코드에 직접 포함되지 않도록 해야 합니다. 정기적으로 설정을 점검하고, 사용하지 않는 서버는 비활성화하는 것도 보안을 위한 좋은 습관입니다.
문제 해결 및 디버깅
MCP 서버가 제대로 작동하지 않을 때는 몇 가지 체크포인트가 있습니다.
- Claude Desktop 재시작 후 입력창 왼쪽 하단에 슬라이더 아이콘이 나타나는지 확인해야 합니다.
- 서버가 인식되지 않는다면 설정 파일의 JSON 문법을 확인하고, 명령어 경로가 올바른지 점검해야 합니다.
- Node.js가 필요한 서버의 경우 node --version 명령으로 설치 여부를 확인할 수 있습니다.
- Claude Desktop 설정에서 디버그 로깅을 활성화하고, Extensions 설정 패널에서 확장 프로그램 로그를 확인하면 문제의 원인을 파악하는 데 도움이 됩니다.
- 환경 변수가 제대로 설정되지 않는 경우가 많으므로, API 키나 토큰 정보가 올바르게 입력되었는지도 반드시 확인해야 합니다.
고급 활용 사례 : 멀티 서버 연동
여러 MCP 서버를 동시에 연결하여 복합적인 워크플로우를 구성할 수 있습니다. 예를 들어, GitHub에서 코드 변경사항을 분석하고, 데이터베이스에서 관련 메트릭을 가져와서, Gmail을 통해 팀에게 리포트를 전송하는 전체 과정을 하나의 명령으로 실행할 수 있습니다. 이런 통합된 워크플로우는 개발팀의 생산성을 크게 향상시킬 수 있으며, 반복적인 업무를 자동화하는 데 매우 효과적입니다. 설정 파일에 여러 서버를 동시에 구성하고, Claude가 상황에 맞는 적절한 도구를 선택하여 작업을 수행하도록 할 수 있습니다.
마무리
2025년 3월 OpenAI가 공식적으로 MCP를 채택했고, Google DeepMind도 Gemini 모델과 관련 인프라에서 MCP 지원을 확정하면서 MCP는 빠르게 AI 산업의 표준으로 자리 잡고 있습니다.
이는 단순히 Claude Desktop만의 기능이 아니라, AI 생태계 전체에서 통용되는 범용적인 프로토콜로 발전하고 있다는 의미입니다. 개발자들에게는 한 번 작성한 MCP 서버를 다양한 AI 플랫폼에서 재사용할 수 있는 기회를 제공하며, 이는 개발 효율성을 크게 향상시킬 것으로 예상됩니다. 앞으로 더 많은 서비스와 플랫폼이 MCP를 지원하게 되면서, AI와 기존 시스템 간의 연결이 훨씬 더 쉽고 표준화된 방식으로 이루어질 것입니다.
'AI 코딩' 카테고리의 다른 글
로컬AI 구축의 핵심 : LLM과 임베딩 모델의 협업 (6) | 2025.07.28 |
---|---|
제조업 특화 로컬 LLM 도구 TOP 5 (11) | 2025.07.26 |
[AI코딩.11] AI 코딩 미래 전망과 마무리 - AI 코딩의 다음 단계 (5) | 2025.07.22 |
[AI코딩.10] Augmented 코딩과 Vibe 코딩에 대한 개발자 가이드 (9) | 2025.07.21 |
[git] Synology Drive에서 .git 폴더 동기화 설정 방법 (6) | 2025.07.19 |