MCP stdio 설정 방법 — npx·uvx 명령어로 MCP 서버 실행하는 법
MCP stdio 설정의 전체 흐름을 npx·uvx 명령어 예시와 함께 단계별로 설명합니다. Claude Desktop·Claude Code에서 command 방식으로 MCP 서버를 연결하는 완전 가이드입니다.
MCP 서버를 Claude에 연결하는 가장 보편적인 방법은 stdio 방식입니다. command 필드에 npx 또는 uvx를 지정하면 Claude가 서버 프로세스를 직접 실행하고 표준 입출력으로 통신합니다. 이 가이드는 설정 파일 구조 이해부터 실제 서버 추가, 연결 확인, 흔한 오류 해결까지 완전히 다룹니다. API 키가 필요 없는 서버라면 명령어 세 줄로 연결이 끝납니다.
stdio 방식이란 무엇인가
MCP(Model Context Protocol)는 AI 클라이언트와 서버가 통신하는 방식을 두 가지로 나눕니다.
| 전송 방식 | 설명 | 주요 사용처 |
|---|---|---|
| stdio | 클라이언트가 서버 프로세스를 로컬에서 직접 실행, 표준 입출력으로 통신 | 공개 오픈소스 서버 대부분 |
| SSE | HTTP 서버로 원격 연결 (Server-Sent Events) | 원격 호스팅 서버, 유료 서비스 |
공개된 MCP 서버의 90% 이상은 stdio 방식으로 배포됩니다. claude_desktop_config.json(또는 .mcp.json)에 command·args·env 세 필드만 채우면 됩니다.
Claude Desktop / Claude Code
│ (표준 입력/출력)
▼
npx kordoc setup (또는 uvx some-mcp-server)
│
▼
MCP 서버 프로세스 (로컬 실행)
│
▼
외부 API / 파일 시스템 / 데이터베이스
npx vs uvx: 런타임 선택 기준
npx는 Node.js 패키지를, uvx는 Python 패키지를 실행합니다. 서버 저장소의 언어를 확인하거나 README의 설치 명령어를 보면 바로 알 수 있습니다.
| 구분 | npx | uvx |
|---|---|---|
| 언어 | JavaScript / TypeScript | Python |
| 전제 조건 | Node.js 18 이상 | Python 3.11 이상 + uv 설치 |
| 패키지 출처 | npm 레지스트리 | PyPI |
| 설치 없이 실행 | 가능 (-y 플래그) | 가능 |
| 예시 명령 | npx -y kordoc setup | uvx some-python-mcp |
uv가 없다면 아래 명령으로 먼저 설치합니다.
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
준비물
- Claude Desktop 최신 버전 또는 Claude Code CLI
- Node.js 18 이상: npx 방식 서버 실행에 필요
- Python 3.11 이상 + uv: uvx 방식 서버 실행에 필요
- 텍스트 에디터: 설정 파일 편집용 (VS Code, Notepad++ 등)
단계별 MCP stdio 설정 방법
1단계: 설정 파일 위치 확인
Claude Desktop의 MCP 설정 파일 위치는 운영체제마다 다릅니다.
| OS | 파일 경로 |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
파일이 없으면 새로 만듭니다. 비어 있는 파일이라면 다음 기본 구조를 붙여넣으세요.
{
"mcpServers": {}
}
2단계: npx 방식 서버 추가
npm에 게시된 MCP 서버는 command를 npx로 설정합니다. -y 플래그를 추가하면 설치 여부를 묻는 확인 프롬프트를 건너뜁니다.
아래는 코르독(KorDoc) — HWP·PDF·DOCX를 Markdown으로 변환하는 서버 — 설정 예시입니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
HWP-MCP — 한글 문서 읽기·편집·생성 서버 — 를 추가할 때는 다음과 같이 기존 mcpServers 블록 안에 나란히 씁니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
},
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
}
}
}
API 키가 필요한 서버라면 env 필드를 추가합니다.
{
"mcpServers": {
"some-api-server": {
"command": "npx",
"args": ["-y", "some-mcp-package"],
"env": {
"API_KEY": "여기에_API_키_입력"
}
}
}
}
3단계: uvx 방식 서버 추가
Python 기반 MCP 서버는 command를 uvx로 설정합니다. 로컬 저장소를 클론해서 실행해야 하는 경우에는 uv와 --directory 옵션을 함께 씁니다.
PyPI에 게시된 Python 패키지 (uvx 직접 실행):
{
"mcpServers": {
"example-python-mcp": {
"command": "uvx",
"args": ["example-python-mcp"],
"env": {
"API_KEY": "여기에_API_키_입력"
}
}
}
}
로컬 클론이 필요한 경우 (uv + —directory):
# 먼저 저장소를 클론합니다
git clone https://github.com/example/some-mcp-server ~/Downloads/some-mcp-server
{
"mcpServers": {
"some-mcp-server": {
"command": "uv",
"args": [
"--directory", "/Users/사용자명/Downloads/some-mcp-server",
"run", "server.py"
],
"env": {
"API_KEY": "여기에_API_키_입력"
}
}
}
}
경로 안의 사용자명을 실제 계정 이름으로 바꿔주세요. Windows라면 C:\Users\사용자명\Downloads\some-mcp-server 형식을 사용합니다.
4단계: Claude Desktop 재시작
설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료합니다. macOS라면 메뉴 막대의 트레이 아이콘도 확인하세요. 이후 다시 실행하면 등록된 MCP 서버가 자동으로 기동됩니다.
새 대화창을 열어 아래 두 가지를 확인합니다.
- 입력창 왼쪽의 도구(망치) 아이콘 클릭 → 서버 이름과 도구 목록이 보이면 연결 성공
- Claude에게
"등록된 MCP 도구 목록을 알려줘"라고 물어보면 서버가 제공하는 도구를 나열합니다
5단계: Claude Code에서 동일 설정 적용
Claude Code를 사용하는 경우 설정 파일은 .mcp.json입니다. 구조는 동일합니다.
프로젝트별 설정 (프로젝트 루트에 .mcp.json 파일 생성):
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
위 예시는 한포지(HwpForge) — HWPX 문서를 AI 에이전트가 읽고 쓰고 변환하는 서버 — 설정입니다. API 키가 필요 없으므로 env 필드를 생략했습니다.
전역 설정 (모든 프로젝트에 적용):
# 사용자 범위로 등록 (정의는 ~/.claude.json에 저장됩니다)
claude mcp add --scope user 서버이름 -- npx -y 패키지명
설정 파일 구조 전체 요약
claude_desktop_config.json
└── mcpServers (객체)
├── 서버키1
│ ├── command → "npx" 또는 "uvx" 또는 "uv"
│ ├── args → [패키지명, 옵션, ...]
│ └── env → {"KEY": "value", ...} (선택)
└── 서버키2
├── command
├── args
└── env
서버키는 사용자가 원하는 임의의 이름을 사용할 수 있습니다. Claude가 이 이름으로 서버를 식별합니다.
흔한 오류와 해결 방법
오류: 서버가 도구 목록에 나타나지 않음
가장 흔한 원인은 JSON 문법 오류입니다. 쉼표 하나가 빠지거나 중괄호가 맞지 않으면 Claude Desktop이 파일 전체를 무시합니다.
아래 방법으로 확인하세요.
# macOS/Linux: JSON 문법 검사 (파이썬 내장)
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
오류 없이 JSON이 출력되면 문법은 정상입니다.
오류: npx 명령을 찾을 수 없음
Node.js가 설치되지 않았거나 PATH에 등록되지 않은 경우입니다.
# Node.js 버전 확인
node --version # v18.0.0 이상이어야 함
npx --version
설치되지 않았다면 nodejs.org에서 LTS 버전을 설치하세요.
오류: uvx 명령을 찾을 수 없음
uv 패키지 매니저가 설치되지 않은 경우입니다. 위의 준비물 섹션의 설치 명령을 참고하세요. 설치 후 터미널을 새로 열어야 PATH가 적용됩니다.
오류: 패키지를 찾을 수 없음 (404/Not Found)
패키지명이 틀렸거나 npm/PyPI에 아직 게시되지 않은 경우입니다. 서버의 GitHub README에서 정확한 패키지명을 복사해 사용하고, 오타 여부를 꼭 확인하세요.
서버는 실행되지만 오류 반환
서버가 필요한 API 키나 환경변수를 찾지 못할 때 발생합니다. env 블록에 키 이름이 정확히 입력됐는지, 값에 불필요한 공백이 없는지 확인하세요.
여러 서버를 함께 쓸 때 권장 순서
- 우선 서버 1개만 추가해 연결을 확인한 뒤 추가 서버를 등록합니다.
- 서버가 많아지면 시작 속도가 느려질 수 있으므로, 실제로 사용하는 서버만 활성화합니다.
- 사용하지 않는 서버는 해당 블록을 통째로 삭제(또는 키 이름 앞에
_를 붙여 임시 비활성화)합니다.
개발도구 카테고리에서 더 많은 MCP 서버를 탐색할 수 있습니다.
다음 단계
stdio 설정 방법을 익혔다면 바로 실제 서버를 연결해 보세요.
- 코르독(KorDoc): HWP·HWPX·PDF·XLSX·DOCX를 Markdown으로 변환. API 키 불필요,
npx -y kordoc setup으로 바로 시작. - HWP-MCP: 한글 문서를 Claude가 직접 읽고 편집.
npx -y hwp-mcp한 줄로 설치. - 한포지(HwpForge): HWPX 문서 읽기·쓰기·변환 지원.
npx -y @hwpforge/mcp로 시작.
더 많은 MCP 서버를 찾고 있다면 전체 서버 목록을 확인하거나, 새로운 서버를 발견했다면 서버 등록에 기여해 주세요.
자주 묻는 질문
npx와 uvx의 차이는 무엇인가요?
npx는 Node.js 생태계의 패키지 실행 도구입니다. npm에 게시된 MCP 서버를 설치 없이 바로 실행할 수 있습니다. uvx는 Python 생태계의 uv 도구가 제공하는 실행 명령으로, PyPI 패키지를 격리된 가상환경에서 실행합니다. 서버의 언어(JavaScript/TypeScript이면 npx, Python이면 uvx)에 따라 선택하면 됩니다.
MCP 서버가 도구 목록에 나타나지 않을 때 어떻게 하나요?
설정 파일의 JSON 문법 오류가 가장 흔한 원인입니다. 쉼표 누락, 따옴표 불일치 등을 확인하세요. 그다음 터미널에서 해당 npx 또는 uvx 명령을 직접 실행해 패키지 기동이 정상인지 확인합니다. 마지막으로 Claude Desktop을 완전히 종료(트레이 아이콘 포함)한 뒤 재시작하세요.
API 키를 설정 파일에 직접 써도 괜찮나요?
claude_desktop_config.json은 로컬 파일이므로 개인 사용 환경에서는 일반적으로 허용됩니다. 다만 이 파일을 git에 올리거나 타인과 공유해서는 안 됩니다. 팀 환경이라면 운영체제 환경변수에 키를 설정한 뒤 env 블록에서 참조하는 방식을 권장합니다.
Claude Code에서도 동일한 stdio 설정을 사용할 수 있나요?
네. Claude Code는 프로젝트 루트의 .mcp.json 파일을 읽습니다. 키 이름은 mcpServers이고 내부 구조(command, args, env)는 Claude Desktop과 동일합니다. 전역으로 적용하려면 claude mcp add --scope user 명령으로 등록합니다.
여러 MCP 서버를 동시에 등록할 수 있나요?
네. mcpServers 객체 안에 서버를 여러 개 나란히 추가하면 됩니다. 각 서버는 고유한 키 이름을 갖습니다. Claude Desktop은 시작 시 등록된 모든 서버를 동시에 기동합니다.
설정 파일을 수정할 때마다 Claude Desktop을 재시작해야 하나요?
네. Claude Desktop은 시작 시에만 설정 파일을 읽으므로, 변경 사항을 반영하려면 반드시 완전히 종료하고 다시 실행해야 합니다.