MCP 서버 설치 가이드 — npx·uvx·pip 방식 선택과 Claude Desktop 연결

Q: npx와 uvx 중 어떤 방식을 써야 하나요?

MCP 서버가 Node.js(npm 패키지)로 만들어졌으면 npx, Python(PyPI 패키지)로 만들어졌으면 uvx 또는 pip를 사용합니다. 서버의 GitHub 저장소 또는 README에 권장 방식이 명시되어 있습니다.

Q: npx로 실행하면 매번 다운로드가 일어나나요?

npx는 기본적으로 캐시를 활용하므로 처음 실행 후에는 로컬 캐시에서 빠르게 로드됩니다. -y 플래그를 추가하면 확인 프롬프트 없이 자동 설치·실행됩니다.

Q: Claude Desktop 설정 파일 위치는 어디인가요?

macOS는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows는 %APPDATA%\Claude\claude_desktop_config.json에 있습니다.

Q: pip 방식과 uvx 방식의 차이는 무엇인가요?

pip는 현재 Python 환경에 전역 설치하는 방식이고, uvx는 uv 도구를 이용해 격리된 가상 환경에서 실행합니다. uvx는 의존성 충돌 위험이 없어 MCP 서버에 더 권장됩니다.

Q: MCP 서버가 Claude Desktop에 나타나지 않으면 어떻게 하나요?

JSON 문법 오류, 경로 오타, 런타임 미설치가 가장 흔한 원인입니다. Claude Desktop 로그(개발자 도구 또는 ~/Library/Logs/Claude/)에서 오류 메시지를 확인하고, 설정 파일을 JSON 검증기로 검사해 보세요.

Q: API 키가 필요한 MCP 서버는 어떻게 설정하나요?

mcpServers 항목의 env 블록에 환경 변수를 추가합니다. 예를 들어 API_KEY 가 필요하면 env 객체 안에 해당 키-값 쌍을 넣으면 됩니다. 자세한 형식은 아래 본문 단계를 참고하세요.

MCP(Model Context Protocol) 서버를 Claude Desktop에 연결하는 방식은 서버가 어떤 언어로 만들어졌느냐에 따라 갈립니다. Node.js 서버는 npx, Python 서버는 uvx 또는 pip, 그 외 비공개·커스텀 서버는 직접 빌드로 실행합니다. 이 가이드는 “내 서버는 어떤 방식인가”를 판별하는 기준에서 시작해, 설정 파일 작성, 환경 변수 처리, 연결이 안 될 때의 진단 순서까지 한 흐름으로 다룹니다.

설정 자체는 claude_desktop_config.json에 command와 args를 적는 몇 줄이 전부입니다. 막히는 지점은 거의 항상 (1) 방식 선택을 잘못했거나 (2) JSON 문법·경로가 틀렸거나 (3) 런타임이 없어서입니다. 이 세 가지를 순서대로 짚는 것이 이 문서의 목표입니다.

먼저 결정할 것: 어떤 방식으로 실행하는가

Claude Desktop은 MCP 서버를 별도 프로세스로 띄워 stdio로 통신합니다. 따라서 “이 서버를 어떤 명령으로 실행하는가”가 설정의 핵심이고, 이는 서버의 배포 형태에 따라 정해집니다.

방식	대상 언어	필요 런타임	동작 방식	권장 상황
`npx`	Node.js	Node.js 18+	npm 패키지를 받아 캐시 후 실행	npm에 배포된 Node.js 서버
`uvx`	Python	uv 도구	격리된 임시 환경에서 실행	PyPI에 배포된 Python 서버(기본 권장)
`pip`	Python	Python 3.10+	현재 환경에 설치 후 실행	uv를 쓸 수 없는 환경
직접 빌드	다양	소스 빌드 도구	빌드 산출물·CLI를 직접 실행	비공개·커스텀 서버

판별 기준은 단순합니다. 서버의 GitHub 저장소 README나 MCP모아 서버 페이지의 install_type을 보면 됩니다. npm 패키지면 npx, PyPI 패키지면 uvx/pip입니다. 가장 흔한 실수가 Python 서버를 npx로 적거나 그 반대로 적는 것이므로, 추측하지 말고 README의 권장 명령을 그대로 따르세요.

uvx vs pip: 둘 다 Python 서버를 실행하지만, pip는 현재 Python 환경에 패키지를 설치하므로 다른 패키지와 의존성이 충돌할 수 있습니다. uvx는 실행할 때마다 격리된 환경을 쓰기 때문에 충돌 위험이 없어, Python 서버에는 uvx를 우선 권장합니다.

연결 구조 한눈에 보기

설정값이 어디에 영향을 주는지 알면 디버깅이 쉬워집니다.

Claude Desktop
    │
    │  ① command + args 로 프로세스 실행
    ▼
MCP 서버 프로세스 (npx / uvx / pip)
    │
    │  ② stdio(표준입출력)로 도구 목록·호출 주고받음
    ▼
외부 서비스(HTTP API) 또는 로컬 파일

command/args가 틀리면 ①에서 프로세스가 아예 안 뜨고, 런타임이나 의존성 문제면 ②까지 갔다가 끊깁니다. 증상이 “목록에 안 나타남”이면 ①, “잠깐 떴다 사라짐”이면 ②를 의심하는 식으로 좁혀갈 수 있습니다.

준비물

Claude Desktop 최신 버전 (claude.ai/download)
선택한 방식에 맞는 런타임 — 셋 다 깔 필요는 없고 쓰려는 서버에 맞는 것만:
- Node.js 18 이상 — npx 사용 시
- uv 도구 — uvx 사용 시 (curl -LsSf https://astral.sh/uv/install.sh | sh)
- Python 3.10 이상 — pip 사용 시
텍스트 편집기 (VS Code, nano 등)

단계별 설치 방법

1단계 — 런타임 확인

쓰려는 방식의 런타임이 있는지 먼저 확인합니다. 버전 명령이 정상 출력되면 설치돼 있는 것입니다.

node --version     # npx 방식: v18.0.0 이상
uv --version       # uvx 방식
python3 --version  # pip 방식: 3.10 이상

Node.js가 없으면 nodejs.org, uv가 없으면 공식 문서(docs.astral.sh/uv)에서 설치합니다.

2단계 — 서버의 설치 방식·명령 확인

대상 서버의 GitHub README 또는 MCP모아 서버 페이지에서 install_type과 정확한 패키지명을 확인합니다. 한국 문서 파일을 다루는 서버들의 예시는 다음과 같습니다.

서버	설치 방식	실행 명령
코르독 (KorDoc)	npx	`npx -y kordoc setup`
HWP-MCP	npx	`npx -y hwp-mcp`
한포지 (HwpForge)	npx	`npx -y @hwpforge/mcp`

여기서 본 command(예: npx)와 args(예: -y, kordoc, setup)를 다음 단계의 JSON에 그대로 옮겨 적게 됩니다. -y 플래그는 npx가 설치 확인 프롬프트를 띄우지 않고 바로 실행하도록 하는 옵션으로, 백그라운드로 실행되는 MCP 서버에는 사실상 필수입니다.

3단계 — Claude Desktop 설정 파일 열기

설정 파일 위치는 운영체제마다 다릅니다.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS에서 터미널로 바로 열려면:

open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

파일이 없으면 새로 만들면 됩니다. 처음 만든다면 최상위에 { "mcpServers": {} } 골격부터 넣고 시작하세요.

4단계 — mcpServers 항목 추가

2단계에서 확인한 실행 명령을 방식별로 옮겨 적습니다.

npx 방식 (Node.js 서버)

실행 명령 npx -y kordoc setup은 command에 npx, 나머지 토큰을 args 배열에 순서대로 넣습니다.

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

uvx 방식 (Python 서버, 격리 실행 권장)

패키지명 자리에는 PyPI에 배포된 실제 패키지명을 넣습니다.

{
  "mcpServers": {
    "my-python-mcp": {
      "command": "uvx",
      "args": ["패키지명"]
    }
  }
}

pip 방식 (Python 서버, 전역 설치 후 실행)

pip로 설치한 서버는 보통 python3 -m 모듈명 형태로 실행하거나, 설치 시 생성된 CLI 바이너리를 직접 command로 지정합니다.

{
  "mcpServers": {
    "my-pip-mcp": {
      "command": "python3",
      "args": ["-m", "패키지명"]
    }
  }
}

API 키가 필요한 서버

키·토큰 같은 값은 args가 아니라 env 블록에 환경 변수로 넣습니다. 변수 이름은 서버 README가 요구하는 이름과 정확히 일치해야 합니다.

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["-y", "서버패키지명"],
      "env": {
        "API_KEY": "여기에_실제_키_입력"
      }
    }
  }
}

5단계 — 재시작 및 연결 확인

설정 파일을 저장합니다.
Claude Desktop을 완전히 종료했다가 다시 시작합니다. (창만 닫는 것으로는 반영되지 않습니다.)
새 대화를 시작하고 입력창 옆 도구 아이콘(망치 모양)을 클릭합니다.
추가한 서버 이름과 도구 목록이 보이면 성공입니다.

연결이 안 될 때: 증상별 진단

대부분의 문제는 아래 표 안에 있습니다. 증상을 먼저 찾고 원인을 좁히세요.

증상	흔한 원인	해결
서버가 도구 목록에 아예 안 보임	JSON 문법 오류	설정 파일을 jsonlint.com 등으로 검증
`command not found`	해당 런타임(npx/uv) 미설치 또는 PATH 누락	1단계 런타임 확인 후 재시도
떴다가 곧 끊김	의존성 버전 충돌	uvx 방식으로 전환하거나 서버 저장소 이슈 확인
API 오류 반환	env 변수 누락·오타	`env` 키 이름과 값을 README와 대조
한글 경로에서 실패	경로 인코딩 문제	설정 파일 경로에 한글·공백 포함 여부 확인

로그로 원인 확인하기

표로 좁혀지지 않으면 로그가 가장 확실한 단서입니다.

# macOS — MCP 관련 로그 실시간 확인
tail -f "$HOME/Library/Logs/Claude/mcp*.log"

Windows는 %APPDATA%\Claude\logs\ 폴더에서 확인합니다. 로그에 찍힌 실행 명령과 에러 메시지를 보면 command/args가 잘못됐는지, 런타임이 없는지 바로 구분됩니다.

여러 서버를 동시에 등록하기

mcpServers 객체 안에 항목을 콤마로 구분해 나열하면 됩니다. Claude Desktop은 시작 시 등록된 서버를 병렬로 실행합니다.

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

서버가 많을수록 시작 시간이 다소 길어질 수 있습니다. JSON은 주석을 지원하지 않으므로, 잠시 끄고 싶은 서버는 항목 자체를 삭제하거나 별도 파일에 보관했다가 다시 붙여 넣는 식으로 관리하세요.

자주 묻는 질문

npx와 uvx 중 어떤 방식을 써야 하나요?

서버가 Node.js(npm 패키지)면 npx, Python(PyPI 패키지)면 uvx 또는 pip를 씁니다. 권장 방식은 서버의 GitHub 저장소나 README에 명시돼 있으니 추측하지 말고 그대로 따르세요.

npx로 실행하면 매번 다운로드가 일어나나요?

아닙니다. npx는 캐시를 활용하므로 첫 실행 이후에는 로컬 캐시에서 빠르게 로드됩니다. -y 플래그를 붙이면 확인 프롬프트 없이 자동으로 설치·실행됩니다.

Claude Desktop 설정 파일 위치는 어디인가요?

macOS는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows는 %APPDATA%\Claude\claude_desktop_config.json입니다.

pip 방식과 uvx 방식의 차이는 무엇인가요?

pip는 현재 Python 환경에 전역 설치하는 방식이고, uvx는 uv 도구로 격리된 환경에서 실행합니다. uvx는 의존성 충돌 위험이 없어 MCP 서버에 더 권장됩니다.

MCP 서버가 Claude Desktop에 나타나지 않으면 어떻게 하나요?

JSON 문법 오류, 경로 오타, 런타임 미설치가 가장 흔한 원인입니다. Claude Desktop 로그(~/Library/Logs/Claude/)에서 메시지를 확인하고, 설정 파일을 JSON 검증기로 검사하세요.

API 키가 필요한 MCP 서버는 어떻게 설정하나요?

mcpServers 항목의 env 블록에 환경 변수로 넣습니다. 변수 이름은 서버 README가 요구하는 이름과 정확히 일치해야 하며, 위 4단계의 “API 키가 필요한 서버” 예시를 참고하세요.

다음 단계

설치가 끝났다면 실제 한국어 문서 처리 서버를 연결해 보세요.

코르독 (KorDoc) — HWP·PDF·DOCX 등 한국 공문서를 Markdown으로 변환
HWP-MCP — 한글 문서를 AI가 직접 읽고 편집
한포지 (HwpForge) — HWPX 문서를 AI 에이전트가 읽고 쓰고 변환
개발 도구 카테고리 전체 보기
MCP 서버 전체 목록