Cline MCP 설치·설정 완전 가이드 — cline_mcp_settings.json과 마켓플레이스
VS Code 확장 Cline에서 MCP 서버를 마켓플레이스 원클릭 또는 cline_mcp_settings.json 직접 편집으로 추가하는 법. 파일 위치, JSON 필드, npx·uvx 구분, 재시작 방법, 오류 해결까지.
VS Code 확장 Cline에서 MCP 서버를 쓰는 방법은 두 가지입니다. Cline 내장 마켓플레이스에서 원클릭 설치하거나, cline_mcp_settings.json 파일을 직접 편집하는 것입니다. 이 가이드는 두 방식을 모두 다루며, 설정 파일 위치 찾기부터 JSON 구조, 서버 재시작, 연결 확인, 흔한 오류 해결까지 순서대로 안내합니다. Claude Desktop 방식과 혼동하기 쉬운 차이점도 함께 짚어드립니다.
Cline에서 MCP가 왜 필요한가
Cline은 VS Code 안에서 동작하는 AI 코딩 에이전트입니다. 기본 상태에서도 파일 편집, 터미널 명령 실행, 브라우저 조작 등의 도구를 사용할 수 있지만, MCP 서버를 연결하면 외부 데이터 소스나 특수 도구를 에이전트 루프에 직접 통합할 수 있습니다. 예를 들어 한글 문서 파싱, 사내 API 호출, 공공 데이터 조회 같은 작업을 Cline이 스스로 판단해 실행하게 됩니다.
사용자 지시
│
▼
Cline (VS Code 에이전트)
│ (cline_mcp_settings.json 파싱)
│ MCP 도구 호출
▼
MCP 서버 (로컬 프로세스, npx / uvx 실행)
│ API 요청 / 파일 처리
▼
외부 서비스 또는 로컬 도구
│ 결과 반환
▼
Cline → 코드/파일/답변 생성
준비물
| 항목 | 버전 / 비고 |
|---|---|
| VS Code | 1.85 이상 권장 |
| Cline 확장 | VS Code 마켓플레이스에서 설치 (ID: saoudrizwan.claude-dev) |
| Node.js | 18 이상 (npx 기반 서버 사용 시) |
| Claude API 키 또는 다른 LLM 키 | Cline 설정에서 입력 |
Cline은 Claude 외에도 OpenAI, Gemini, 로컬 모델 등을 지원하지만, MCP 설정은 LLM 선택과 무관하게 동일합니다.
두 가지 설치 방식 — 무엇을 언제 쓰나
| 방식 | 장점 | 적합한 상황 |
|---|---|---|
| 마켓플레이스 원클릭 | 가장 간단, 자동으로 설정 파일에 기록 | 마켓플레이스에 등록된 검증 서버 |
cline_mcp_settings.json 직접 편집 | 정확하고 버전 관리에 유리, 여러 서버 일괄 추가·팀 공유 가능 | 미등록 서버, 설치 인수 커스텀, 환경변수 주입 |
두 방식은 동일한 설정 파일을 공유하므로 혼용해도 무방합니다.
단계별 설치 방법
1단계 — Cline 확장 설치 및 기본 설정 확인
VS Code를 열고 확장 마켓플레이스(Ctrl+Shift+X / Cmd+Shift+X)에서 Cline을 검색해 설치합니다. 설치 후 좌측 사이드바에 Cline 아이콘이 나타나면 클릭해 패널을 엽니다. API 키 입력 화면이 뜨면 사용할 LLM의 키를 입력하세요.
2단계 — Cline MCP 마켓플레이스에서 서버 찾기 (원클릭 설치)
Cline 패널 상단의 MCP 서버 아이콘(플러그 모양)을 클릭하면 MCP 서버 관리 화면이 열립니다. 여기서 마켓플레이스 탭을 선택하면 Cline이 공식으로 검증한 MCP 서버 목록을 볼 수 있습니다. 원하는 서버를 검색하고 Install 버튼을 누르면 Cline이 자동으로 cline_mcp_settings.json에 항목을 추가하고 서버를 시작합니다.
마켓플레이스 설치가 완료되면 서버 옆에 녹색 점이 표시되며, 이후 Cline 채팅에서 해당 도구를 바로 사용할 수 있습니다.
3단계 — cline_mcp_settings.json 직접 편집
마켓플레이스에 없는 서버를 추가하거나 설치 옵션을 커스텀하려면 설정 파일을 직접 수정합니다.
설정 파일 위치:
| 운영체제 | 경로 |
|---|---|
| macOS | ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json |
| Windows | %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json |
| Linux | ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json |
Cline MCP 서버 관리 화면 하단의 Edit MCP Settings 버튼을 누르면 VS Code가 이 파일을 바로 열어줍니다. 경로를 직접 찾지 않아도 됩니다.
터미널에서 바로 열기:
code 명령으로 설정 파일을 곧장 VS Code에 띄울 수도 있습니다.
# macOS / Linux
code "$HOME/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json"
# Windows (PowerShell)
code "$env:APPDATA\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json"
파일이 없을 때: Cline 확장을 설치하고 VS Code를 한 번 재시작하면 Cline이 초기화될 때 설정 폴더와 파일을 자동으로 만들어 줍니다. 그래도 없다면 해당 경로에 직접 빈 파일을 만들어도 됩니다.
{
"mcpServers": {}
}
4단계 — JSON 구조와 필드 이해하기
mcpServers 객체 안에 서버를 추가합니다. 각 서버는 고유한 이름을 키로 가집니다.
{
"mcpServers": {
"서버-이름": {
"command": "npx",
"args": ["-y", "패키지명"],
"env": {},
"disabled": false,
"alwaysAllow": []
}
}
}
| 필드 | 필수 여부 | 설명 |
|---|---|---|
command | 필수 | 서버를 실행할 프로그램 (npx, uvx, node 등) |
args | 필수 | 실행 인자 배열 |
env | 선택 | API 키 등 환경변수 (불필요하면 생략 가능) |
disabled | 선택 | true로 설정하면 서버를 잠시 비활성화 |
alwaysAllow | 선택 | 사용자 승인 없이 자동 실행할 도구 이름 배열 |
args의 -y 인자는 npx가 패키지 설치를 묻지 않고 바로 실행하도록 합니다.
npx 방식 서버 예시 — KorDoc:
코르독(KorDoc)은 HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 Markdown으로 변환하는 MCP 서버입니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"],
"env": {},
"disabled": false,
"alwaysAllow": []
}
}
}
여러 서버를 동시에 등록하는 예시:
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"],
"env": {},
"disabled": false,
"alwaysAllow": []
},
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"],
"env": {},
"disabled": false,
"alwaysAllow": []
}
}
}
5단계 — 파일 저장 및 변경 반영
파일을 저장하면 Cline이 변경사항을 자동으로 감지해 서버를 재시작합니다. 자동 감지가 동작하지 않을 때는 아래 방법 중 하나로 Cline을 재시작하세요.
방법 A: VS Code 명령 팔레트(F1) → "Developer: Reload Window" 실행
방법 B: VS Code를 완전히 종료 후 다시 실행
방법 C: Cline 확장을 비활성화 후 다시 활성화
6단계 — 연결 상태 확인
MCP 서버 관리 화면으로 돌아와 각 서버 옆의 상태 표시를 확인합니다.
- 녹색 점: 서버가 정상 실행 중
- 빨간 점: 실행 실패 (로그 아이콘을 클릭해 오류 확인)
- 회색 점:
disabled: true로 비활성화된 상태
정상 연결됐다면 Cline 채팅창에 MCP 도구를 사용하는 메시지를 입력해 실제로 호출되는지 테스트합니다.
7단계 — 도구 권한 설정(alwaysAllow)
Cline은 기본적으로 MCP 도구를 실행하기 전 사용자에게 승인을 요청합니다. 자주 쓰는 도구라면 alwaysAllow 배열에 도구 이름을 추가해 자동 승인할 수 있습니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"],
"env": {},
"disabled": false,
"alwaysAllow": ["convert_document", "list_supported_formats"]
}
}
}
도구 이름은 MCP 서버의 공식 문서나 Cline UI에서 서버를 선택하면 나오는 도구 목록에서 확인할 수 있습니다.
npx와 uvx — 실행 명령 구분하기
command 필드에 무엇을 쓸지는 서버가 어떤 언어로 만들어졌는지에 달려 있습니다.
- Node.js 기반 서버 →
npx(Node.js만 설치되어 있으면 바로 사용 가능, 가장 범용적) - Python 기반 서버 →
uvx(uv 패키지 매니저 사용)
서버 공식 문서나 GitHub 저장소의 설치 안내에서 실행 유형을 확인하세요. 확실하지 않을 때는 npx가 더 범용적입니다.
환경변수(API 키) 주입
API 키가 필요한 서버는 env 블록에 키를 추가해야 정상 작동합니다.
{
"mcpServers": {
"my-api-server": {
"command": "npx",
"args": ["-y", "my-mcp-package"],
"env": {
"MY_API_KEY": "여기에_실제_키_입력"
}
}
}
}
설정 파일에 API 키를 직접 저장할 때는 이 파일을 git 등 버전 관리 시스템에 올리지 않도록 주의하세요. 아래에서 다룰 KorDoc·HWP-MCP·HwpForge는 모두 API 키가 필요 없어
env블록을 생략할 수 있습니다.
Claude Desktop 설정과의 차이점
Cline과 Claude Desktop은 모두 MCP를 지원하지만 설정 방식이 다릅니다.
| 항목 | Claude Desktop | Cline (VS Code) |
|---|---|---|
| 설정 파일 이름 | claude_desktop_config.json | cline_mcp_settings.json |
| 파일 위치 | ~/Library/Application Support/Claude/ (macOS) | VS Code globalStorage 내부 |
| 설정 키 이름 | mcpServers | mcpServers (동일) |
| UI 지원 | Claude Desktop 앱의 설정 메뉴 | Cline 패널 내 마켓플레이스 + 설정 편집 |
| 서버 재시작 | Claude Desktop 재시작 필요 | 파일 저장 시 자동 재로드 |
두 클라이언트에서 같은 MCP 서버를 쓰려면 각 설정 파일에 별도로 등록해야 합니다. 공유되지 않습니다. Cursor를 쓴다면 프로젝트 루트의 .cursor/mcp.json에 동일한 서버 정보를 등록하면 됩니다. 내부 JSON 구조는 mcpServers 키를 공통으로 쓰지만 파일 경로가 다릅니다.
흔한 오류와 해결 방법
JSON 파싱 오류 (“Unexpected token”)
cline_mcp_settings.json을 저장했을 때 오류가 발생한다면 JSON 문법 문제일 가능성이 높습니다. 쉼표 누락, 후행 쉼표(trailing comma), 괄호 불일치, 큰따옴표 대신 작은따옴표 사용이 주된 원인입니다.
// 잘못된 예 — 마지막 항목에 쉼표가 있음
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"], // ← 여기 쉼표 불필요
}
}
}
// 올바른 예
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
VS Code 내장 JSON 검사기가 오류 위치를 빨간 밑줄로 표시해 주므로 해당 줄을 먼저 확인하세요.
npx 명령을 찾을 수 없음 (“command not found: npx”)
Node.js가 설치되지 않았거나 VS Code가 시스템 PATH를 인식하지 못하는 경우입니다. 먼저 설치 여부를 확인하세요.
node --version
npm --version
npx --version
Node.js가 없다면 nodejs.org에서 LTS 버전을 설치한 뒤 VS Code를 재시작하세요. VS Code 통합 터미널과 시스템 터미널의 PATH가 다를 수 있으므로, 문제가 지속되면 command를 npx의 절대 경로로 지정하는 방법도 있습니다.
{
"mcpServers": {
"kordoc": {
"command": "/usr/local/bin/npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
절대 경로는 macOS/Linux 터미널에서 which npx로 확인할 수 있습니다.
서버가 “연결 안됨” 상태로 유지될 때
command에 지정한 프로그램이 설치되어 있는지 확인합니다 (which npx또는npx --version).- 터미널에서
args배열의 명령을 직접 실행해 오류 메시지를 확인합니다. - Cline MCP Servers 탭에서 해당 서버 항목을 클릭하면 자세한 오류 로그를 볼 수 있습니다.
서버가 실행됐지만 도구가 보이지 않음
Cline MCP 서버 목록에서 해당 서버를 클릭하면 서버가 노출하는 도구 목록이 표시됩니다. 목록이 비어 있다면 서버 자체의 문제일 수 있으므로, 해당 서버의 GitHub 저장소 이슈를 확인하세요.
MCP 연결이 자꾸 끊어질 때
서버 프로세스가 예기치 않게 종료되는 경우입니다. Cline MCP Servers 탭의 오류 로그를 확인하고, 해당 서버의 GitHub 이슈 페이지에서 알려진 문제를 검색해 보세요. 패키지를 최신 버전으로 업데이트하면 해결되는 경우가 많습니다.
실전 예시 — 한국 공문서 처리 MCP 서버 3종 연결
Cline에 한국 문서 처리 MCP 서버를 연결하면 AI 에이전트가 한글 문서를 직접 읽고 편집하는 작업을 자동화할 수 있습니다. 아래는 한국 업무 환경에서 자주 쓰는 HWP·PDF 처리 서버 3종을 한꺼번에 연결하는 설정입니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
},
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
},
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
각 서버의 역할은 아래 표를 참고하세요. (devtools 카테고리에서 더 찾을 수 있습니다.)
| 서버 | 주요 기능 | API 키 |
|---|---|---|
| 코르독(KorDoc) | HWP·HWPX·PDF·XLSX·DOCX → Markdown 변환 | 불필요 |
| HWP-MCP | 한글(.hwp/.hwpx) 문서 읽기·편집·생성 | 불필요 |
| 한포지(HwpForge) | HWPX 문서 읽기·쓰기·변환 (KS X 6101 지원) | 불필요 |
세 서버 모두 API 키 없이 바로 사용할 수 있어 초기 설정이 간단합니다. 위의 cline_mcp_settings.json 형식으로 Cline에 등록하면 됩니다.
자주 묻는 질문
cline_mcp_settings.json 파일은 어디에 있나요?
운영체제에 따라 경로가 다릅니다. macOS는 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json, Windows는 %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json 경로에 있습니다. Cline UI의 ‘Edit MCP Settings’ 버튼을 누르면 바로 열립니다.
cline_mcp_settings.json 파일이 없으면 어떻게 하나요?
Cline 확장을 VS Code에 설치하고 한 번 실행하면 설정 폴더와 파일이 자동으로 생성됩니다. 파일이 없다면 직접 빈 JSON 파일({"mcpServers": {}})을 해당 경로에 만들어도 됩니다.
Claude Desktop의 claude_desktop_config.json과 Cline 설정 파일은 별개인가요?
네, 완전히 별개입니다. Claude Desktop은 claude_desktop_config.json을, Cline은 cline_mcp_settings.json을 각각 독립적으로 사용합니다. 두 앱 모두에서 MCP 서버를 쓰려면 양쪽 파일에 각각 등록해야 합니다.
Cline MCP 마켓플레이스와 직접 편집, 무엇을 써야 하나요?
마켓플레이스에 등록된 서버라면 원클릭 설치가 가장 간단합니다. 미등록 서버이거나 설치 인수를 커스텀해야 한다면 cline_mcp_settings.json을 직접 편집하는 방법이 필요합니다. 두 방법은 동일한 설정 파일을 공유하므로 혼용해도 무방합니다.
npx 방식과 uvx 방식 중 무엇을 써야 하나요?
Node.js 기반 MCP 서버는 npx, Python 기반 MCP 서버는 uvx(uv 패키지 매니저)를 사용합니다. 서버 공식 문서나 GitHub 저장소의 설치 안내를 확인하세요. 확실하지 않을 때는 npx가 더 범용적이며 Node.js만 설치되어 있으면 바로 사용 가능합니다.
env 필드가 꼭 필요한가요?
API 키나 환경변수가 필요 없는 서버라면 env 필드를 완전히 생략할 수 있습니다. 이 가이드에서 다룬 KorDoc, HWP-MCP, HwpForge는 모두 API 키 없이 사용할 수 있어 env 블록이 필요하지 않습니다. API 키가 필요한 서버는 반드시 env 블록에 키를 추가해야 정상 작동합니다.
MCP 서버를 추가했는데 Cline이 도구를 인식하지 못합니다. 어떻게 하나요?
먼저 cline_mcp_settings.json의 JSON 문법(쉼표 누락, 중괄호 불일치)을 확인하세요. 파일을 저장하면 Cline이 자동으로 재로드하지만, 문제가 지속되면 ‘Developer: Reload Window’를 실행하거나 VS Code 창을 닫고 다시 여세요. 터미널에서 해당 npx 명령을 직접 실행해 패키지 설치 오류 여부도 확인할 수 있습니다.
npx 기반 MCP 서버를 Cline에서 실행하려면 Node.js가 필요한가요?
네, npx를 사용하는 MCP 서버는 Node.js 18 이상이 시스템에 설치되어 있어야 합니다. nodejs.org에서 LTS 버전을 설치한 뒤 터미널에서 node --version으로 버전을 확인하세요.
Cline이 아닌 Cursor나 Claude Desktop에서도 같은 MCP 서버를 쓸 수 있나요?
MCP 서버 자체는 공통이지만, 각 클라이언트마다 설정 파일이 다릅니다. Cursor는 프로젝트 루트의 .cursor/mcp.json, Claude Desktop은 claude_desktop_config.json에 동일한 서버 정보를 등록하면 됩니다.
Cline MCP 연결이 자꾸 끊어집니다.
서버 프로세스가 예기치 않게 종료되는 경우입니다. Cline MCP Servers 탭의 오류 로그를 확인하고, 해당 서버의 GitHub 이슈 페이지에서 알려진 문제를 검색해 보세요. 패키지를 최신 버전으로 업데이트하면 해결되는 경우가 많습니다.
다음 단계
Cline에 첫 MCP 서버를 연결했다면 다음을 시도해 보세요.
- MCP모아 서버 목록에서 더 많은 서버 탐색
- devtools 카테고리에서 개발 도구 특화 서버 찾기
- 코르독(KorDoc) — 한국 공문서 변환 MCP 서버
- HWP-MCP — 한글 문서 편집 MCP 서버
- 한포지(HwpForge) — HWPX 문서 AI 처리 MCP 서버
- 직접 만든 MCP 서버가 있다면 MCP모아에 등록해 커뮤니티와 공유
MCP 생태계는 빠르게 성장하고 있습니다. Cline과 MCP를 조합하면 반복적인 코딩·문서 작업을 에이전트에게 위임할 수 있는 범위가 크게 넓어집니다.