본문 바로가기
M MCP모아
가이드

MCP 클라이언트 설치 방법 총정리 — 입문자를 위한 에디터별 시작 가이드

MCP 클라이언트 설치 방법을 에디터별로 총정리했습니다. Claude Desktop, Cursor, VS Code, Windsurf, Zed 등 주요 클라이언트를 처음 설치하는 방법을 단계별로 안내합니다.

다양한 코드 에디터에 MCP 클라이언트를 설치하는 방법을 안내하는 표지 이미지

MCP(Model Context Protocol) 클라이언트를 처음 설치하려는 분이라면 이 글 하나로 끝냅니다. Claude Desktop·Cursor·VS Code·Windsurf·Zed 등 MCP를 지원하는 주요 에디터의 설치 방법과 설정 위치를 에디터별로 정리했습니다. 어떤 클라이언트를 선택하면 되는지, 설치 후 MCP 서버를 어떻게 연결하는지까지 단계별로 안내합니다.

MCP 클라이언트란 무엇인가요?

MCP(Model Context Protocol)는 Anthropic이 2024년 공개한 오픈 표준입니다. AI 어시스턴트(클라이언트)가 외부 도구나 데이터 소스(서버)와 표준화된 방식으로 통신할 수 있게 해줍니다.

아래 다이어그램처럼 클라이언트가 MCP 서버에 요청을 보내면, 서버는 파일 읽기·API 호출·데이터베이스 조회 등 실제 작업을 수행해 결과를 돌려줍니다.

사용자
  │
  ▼
MCP 클라이언트 (Claude Desktop / Cursor / VS Code 등)
  │  stdio 또는 HTTP/SSE
  ▼
MCP 서버 (kordoc / hwp-mcp / hwpforge 등)
  │
  ▼
외부 시스템 (파일 시스템 / 한국 공공 API / 문서 변환 엔진 등)

클라이언트는 사용자와 대화하는 AI 앱이고, 서버는 특정 기능을 제공하는 백엔드 프로세스입니다. 사용자는 클라이언트를 설치한 뒤 원하는 MCP 서버를 설정 파일에 추가하는 방식으로 기능을 확장합니다.

MCP 지원 클라이언트 목록

현재 MCP를 공식 지원하는 주요 클라이언트는 다음과 같습니다.

클라이언트운영체제무료 사용특징
Claude DesktopmacOS·Windows무료 계정 가능Anthropic 공식 앱, 설정 가장 단순
CursormacOS·Windows·Linux무료 플랜 있음코드 에디터 + AI, JSON 설정
VS Code (GitHub Copilot)전 플랫폼Copilot 구독 필요확장 마켓플레이스 연동
WindsurfmacOS·Windows·Linux무료 플랜 있음Codeium 기반 AI 에디터
ZedmacOS·Linux무료고성능 에디터, context server 방식
Claude Code터미널(전 플랫폼)별도 요금CLI 환경, 프로젝트별 설정

처음 시작하는 분께는 Claude Desktop을 권장합니다. 설정이 가장 직관적이고, Anthropic 공식 문서와 커뮤니티 가이드가 풍부합니다.

준비물

어떤 클라이언트를 선택하든 아래 두 가지는 미리 준비하세요.

  • Node.js 18 이상: 대부분의 MCP 서버가 npx로 실행됩니다. nodejs.org에서 LTS 버전을 설치하세요.
  • 텍스트 에디터: JSON 설정 파일을 수정할 때 필요합니다. VS Code, Cursor, 메모장 어느 것이든 괜찮습니다.

Python 기반 MCP 서버를 사용하려면 uv 패키지 매니저도 필요합니다.

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Claude Desktop에서 MCP 서버 연결하기

1단계: Claude Desktop 설치

claude.ai/download에서 운영체제에 맞는 버전을 다운로드해 설치합니다.

2단계: 설정 파일 열기

Claude Desktop의 MCP 설정 파일은 아래 경로에 있습니다.

운영체제설정 파일 경로
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json

파일이 없으면 직접 생성하면 됩니다.

3단계: MCP 서버 등록

설정 파일에 아래와 같이 원하는 MCP 서버를 추가합니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "mcp"]
    }
  }
}

여러 서버를 동시에 등록하려면 mcpServers 객체 안에 서버를 나란히 추가하면 됩니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "mcp"]
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

4단계: Claude Desktop 재시작

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 시작합니다. 채팅창 왼쪽 하단에 망치(도구) 아이콘이 나타나면 MCP 서버가 정상 연결된 것입니다.

Cursor에서 MCP 서버 연결하기

Cursor는 프로젝트 전역 설정과 프로젝트별 설정을 모두 지원합니다.

전역 설정

~/.cursor/mcp.json 파일에 서버를 등록합니다. 파일이 없으면 생성하세요.

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

프로젝트별 설정

프로젝트 루트에 .cursor/mcp.json 파일을 만들면 해당 프로젝트에서만 서버가 활성화됩니다. 팀원과 설정을 공유할 때 유용합니다.

설정 후 Cursor를 재시작하거나 Cursor Settings > MCP 메뉴에서 서버 목록을 확인하세요.

VS Code에서 MCP 서버 연결하기

VS Code는 GitHub Copilot 확장(v1.99 이상)을 통해 MCP를 지원합니다.

사용자 설정 (settings.json)에 다음을 추가합니다.

{
  "github.copilot.chat.mcp.servers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"],
      "type": "stdio"
    }
  }
}

또는 VS Code 명령 팔레트(Ctrl+Shift+P / Cmd+Shift+P)에서 “MCP: Add Server” 를 실행해 GUI로 추가할 수도 있습니다.

Windsurf에서 MCP 서버 연결하기

Windsurf는 ~/.codeium/windsurf/mcp_config.json 파일에서 MCP를 설정합니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "mcp"]
    }
  }
}

Windsurf 메뉴 Windsurf Settings > Cascade > MCP Servers 에서 설정 파일 경로를 확인하거나 GUI로 서버를 추가할 수 있습니다.

흔한 오류와 해결 방법

MCP 클라이언트를 처음 설정할 때 자주 만나는 오류를 정리했습니다.

JSON 문법 오류

설정 파일에 쉼표가 빠지거나 따옴표가 잘못된 경우 클라이언트가 서버를 인식하지 못합니다.

오류 예시: Unexpected token } in JSON at position 123
해결: JSON 유효성 검사 사이트(예: jsonlint.com)에 설정 파일 내용을 붙여넣어 문법을 확인하세요.

npx 명령을 찾을 수 없음

Node.js가 설치되어 있지 않거나 PATH에 등록되지 않은 경우입니다.

# Node.js 버전 확인
node --version
npm --version
npx --version

18 이상의 버전이 출력되어야 합니다. 버전이 낮거나 명령을 찾을 수 없다면 nodejs.org에서 최신 LTS를 재설치하세요.

서버가 시작됐지만 도구가 나타나지 않음

클라이언트를 완전히 종료하지 않고 재시작한 경우, 설정이 반영되지 않을 수 있습니다. 작업 관리자(Windows) 또는 활성 상태 보기(macOS)에서 클라이언트 프로세스가 완전히 종료됐는지 확인하세요.

에디터별 설정 파일 경로 한눈에 보기

클라이언트설정 파일 경로
Claude Desktop (macOS)~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)%APPDATA%\Claude\claude_desktop_config.json
Cursor (전역)~/.cursor/mcp.json
Cursor (프로젝트).cursor/mcp.json (프로젝트 루트)
VS Codesettings.json > github.copilot.chat.mcp.servers
Windsurf~/.codeium/windsurf/mcp_config.json
Zed~/.config/zed/settings.json > context_servers

자주 묻는 질문

MCP 클라이언트와 MCP 서버의 차이는 무엇인가요?

MCP 클라이언트는 Claude Desktop·Cursor처럼 AI 어시스턴트가 탑재된 앱이고, MCP 서버는 그 앱에 연결해 특정 기능(파일 읽기, 검색, API 호출 등)을 제공하는 백엔드 프로세스입니다. 사용자는 클라이언트를 설치한 뒤 원하는 MCP 서버를 추가하는 방식으로 사용합니다.

MCP를 사용하려면 유료 구독이 필요한가요?

클라이언트마다 다릅니다. Claude Desktop은 무료 계정으로도 MCP 서버를 연결할 수 있습니다. 다만 Claude Pro 이상에서 더 긴 컨텍스트와 높은 사용 한도를 제공합니다. Cursor는 무료 플랜에서도 MCP를 지원하지만 월 사용량 제한이 있습니다. VS Code GitHub Copilot 확장은 Copilot 구독이 필요합니다.

npx와 uvx 중 무엇을 써야 하나요?

MCP 서버가 Node.js 기반이라면 npx, Python 기반이라면 uvx(uv 패키지 매니저)를 씁니다. 서버의 README나 설치 명령을 확인하면 어느 쪽인지 알 수 있습니다. 모르면 npx를 먼저 시도하고, 실패하면 uvx를 사용해 보세요.

Claude Desktop에서 MCP 서버를 추가해도 반응이 없을 때는 어떻게 하나요?

claude_desktop_config.json 파일의 JSON 문법 오류가 가장 흔한 원인입니다. JSON 유효성 검사 도구로 파일을 확인하고, Claude Desktop을 완전히 종료한 뒤 재시작하세요. 그래도 안 되면 터미널에서 직접 install_cmd를 실행해 에러 메시지를 확인하세요.

Windows에서 Claude Desktop MCP 설정 파일은 어디 있나요?

Windows에서는 %APPDATA%\Claude\claude_desktop_config.json 경로에 있습니다. 파일 탐색기 주소창에 해당 경로를 붙여넣으면 바로 이동할 수 있습니다.

여러 개의 MCP 서버를 동시에 사용할 수 있나요?

네, 가능합니다. claude_desktop_config.json의 mcpServers 객체에 서버를 여러 개 등록하면 됩니다. Claude Desktop은 시작 시 등록된 모든 서버를 병렬로 실행하므로, 서버가 많아질수록 시작 시간이 약간 길어질 수 있습니다.

다음 단계: 한국 특화 MCP 서버 연결해 보기

클라이언트를 설치했다면 이제 원하는 MCP 서버를 연결할 차례입니다. 한국 공문서 처리에 유용한 서버 몇 가지를 소개합니다.

  • 코르독(KorDoc): HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 Markdown으로 변환합니다. npx -y kordoc setup 한 줄로 설치할 수 있습니다.
  • HWP-MCP: AI 어시스턴트가 한글(.hwp/.hwpx) 문서를 직접 읽고 편집·생성할 수 있게 해주는 서버입니다. npx -y hwp-mcp 로 설치합니다.
  • 한포지(HwpForge): HWPX 문서를 AI 에이전트가 읽고 쓰고 변환할 수 있게 해주는 서버입니다. KS X 6101 한컴 한글 표준을 지원합니다. npx -y @hwpforge/mcp 로 설치합니다.

더 많은 한국 특화 MCP 서버는 개발 도구 카테고리에서 찾아보실 수 있습니다. 전체 서버 목록은 MCP 서버 디렉토리에서 확인하세요.

이 글과 관련된 MCP 서버