준비물
- Claude Desktop / Cursor / VS Code 중 하나 이상이 설치되어 있어요
- 설치하려는 MCP 서버가 필요로 하는 런타임 (대부분 Node.js나 Python, 일부는 추가 의존성 필요)
- API 인증 정보 준비 (예: GitHub 토큰) — 설정하는 동안 필요해요
Claude Desktop
그래픽 화면 조작:
- Claude Desktop 열기 → Settings(설정)
- Developer로 이동 → Edit Config 클릭
claude_desktop_config.json의mcpServers항목에 서버를 추가해요:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "여기에-토큰-입력" }
}
}
}
파일을 저장하고 Claude Desktop을 재시작하세요. 새 도구가 왼쪽 사이드바의 도구 목록에 나타나요. 명령어와 인수는 항상 서버의 README를 따르세요.
Cursor
- 명령 팔레트 열기 (
Ctrl+Shift+P/Cmd+Shift+P) - Cursor Settings > MCP를 찾아 선택
- Add New MCP Server 클릭, 전송 방식(stdio 또는 SSE)을 고르고 명령/인수를 채워요
VS Code
- MCP Client 확장 설치 (또는 MCP 지원이 내장된 Copilot / 확장 사용)
- 확장 설정에서 Claude Desktop과 같은 JSON 형식으로
mcpServers를 구성해요 - 변경이 적용되도록 VS Code 창을 다시 로드해요
화면은 클라이언트 버전에 따라 달라질 수 있어요 — 정확한 단계는 항상 공식 문서를 확인하고, 명령/JSON 구조는 항상 서버의 README를 따르세요.
자주 발생하는 오류 해결
| 오류 | 원인 | 해결 |
|---|---|---|
| command not found | Node/Python 런타임이 없거나 PATH에 없어요 | 런타임을 설치하고 클라이언트를 재시작하세요 |
| 401 / 403 | API 인증 정보가 잘못됐거나 만료됐어요 | 토큰을 재발급하고 env 설정을 다시 확인하세요 |
| Connection refused | SSE 서버 주소가 틀렸거나 서비스가 실행 중이 아니에요 | URL + 포트를 확인하고 서버가 온라인인지 확인하세요 |
| Tool not found | 클라이언트를 재시작하지 않아 설정 변경이 로드되지 않았어요 | 설정 저장 후 클라이언트 앱을 완전히 재시작하세요 |
보안 주의사항
- 토큰은 로컬 설정 파일에만 남아요 — 절대 Git에 올리지 마세요 (
.gitignore잊지 마세요) - 믿을 만하고 평판 좋은 프로젝트의 서버만 설치하세요 — 검증되지 않은 서버는 내 데이터를 빼돌릴 수 있어요
- 고권한 서버는 정말 필요할 때만 허용하세요