MCP 서버 uvx 설치 방법 — Python MCP 서버를 uv로 빠르게 실행하기

Python 기반 MCP 서버를 Claude Desktop에 연결할 때 가장 빠른 방법은 uvx 명령을 사용하는 것입니다. pip로 직접 설치하거나 가상환경을 따로 관리하지 않아도 되며, Claude Desktop 설정 파일에 uvx 명령 한 줄만 추가하면 서버가 자동으로 실행됩니다. 이 가이드에서는 uv 설치부터 Claude Desktop 연결까지 전 과정을 단계별로 안내합니다.

uvx가 왜 MCP 설치에 적합한가

Python 패키지를 시스템에 전역으로 설치하면 프로젝트마다 의존성 충돌이 발생하기 쉽습니다. 전통적인 pip + venv 방식은 가상환경 생성, 활성화, 패키지 설치 등 여러 단계를 거쳐야 합니다. uv는 Rust로 작성된 초고속 Python 패키지 관리자이며, 그 하위 명령인 uvx는 Node.js의 npx와 유사하게 동작합니다. 패키지를 격리된 임시 환경에서 직접 실행하므로, MCP 서버처럼 “Claude Desktop이 백그라운드에서 자동 실행해야 하는 프로세스”에 매우 적합합니다.

아래 표에서 세 가지 Python 실행 방식을 비교해 볼 수 있습니다.

방식	격리	속도	설정 복잡도	MCP 서버 적합성
pip (전역)	없음	보통	낮음	의존성 충돌 위험
pip + venv	있음	보통	높음	경로 관리 번거로움
uvx	자동 격리	매우 빠름	낮음	최적

데이터 흐름은 다음과 같습니다.

Claude Desktop
    │  (claude_desktop_config.json 읽기)
    ▼
uvx 명령 실행 (임시 격리 환경 자동 생성)
    │
    ▼
Python MCP 서버 프로세스 (stdio 통신)
    │
    ▼
Claude가 MCP 도구 호출 → 서버 응답 반환

준비물

• macOS 또는 Linux (Windows는 WSL2 환경을 권장합니다)
• Claude Desktop 최신 버전 설치 완료
• 인터넷 연결 (uv 설치 및 패키지 다운로드에 필요)

단계별 설치 방법

1단계: uv 설치 확인

터미널을 열고 아래 명령으로 uv가 설치되어 있는지 확인합니다.

uv --version

설치되어 있지 않다면 운영체제에 맞는 명령으로 설치합니다.

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"

설치 후 새 터미널을 열고 uv --version을 다시 실행해 설치를 확인합니다. uv를 설치하면 uvx 명령도 함께 사용 가능합니다.

2단계: uvx로 Python MCP 서버 실행 테스트

연결하려는 MCP 서버가 PyPI에 배포된 Python 패키지라면 uvx로 직접 실행할 수 있습니다. 예를 들어 some-mcp-server라는 패키지를 테스트하려면 아래와 같이 실행합니다.

uvx some-mcp-server

서버가 정상적으로 시작되면 stdio 대기 상태로 실행됩니다. Ctrl+C로 종료하고 다음 단계로 넘어갑니다.

참고: 관련 서버 목록에 있는 코르독(KorDoc), HWP-MCP, 한포지(HwpForge)는 npx 기반 서버로, 아래에서 별도로 설명합니다.

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

Claude Desktop의 MCP 서버 설정은 JSON 파일로 관리됩니다. 운영체제별 파일 경로는 다음과 같습니다.

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

파일이 없으면 해당 경로에 새 파일을 생성합니다.

4단계: MCP 서버 항목 추가

설정 파일을 열고 mcpServers 블록에 uvx 기반 서버 항목을 추가합니다. 아래는 기본 구조입니다.

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

서버가 추가 인수나 환경 변수를 필요로 하는 경우 다음과 같이 확장합니다.

{
  "mcpServers": {
    "my-python-mcp-server": {
      "command": "uvx",
      "args": ["패키지명", "--옵션", "값"],
      "env": {
        "API_KEY": "여기에_API_키_입력"
      }
    }
  }
}

이미 다른 서버가 설정되어 있다면 mcpServers 블록 안에 항목을 추가하면 됩니다. JSON 형식이 올바른지(쉼표, 괄호) 반드시 확인하세요.

5단계: Claude Desktop 재시작 후 연결 확인

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료합니다. macOS에서는 메뉴바 아이콘을 우클릭해 “Quit”을 선택하거나 Cmd+Q를 사용합니다. 이후 Claude Desktop을 다시 실행하면 설정 파일을 읽어 uvx 명령으로 MCP 서버를 자동 실행합니다.

채팅창 하단에 해당 서버의 도구 아이콘이 표시되면 연결 성공입니다.

npx 기반 서버와의 혼용

실제 프로젝트에서는 Python(uvx) 서버와 JavaScript(npx) 서버를 함께 사용하는 경우가 많습니다. 한국어 문서를 다루는 서버들(KorDoc, HWP-MCP, HwpForge)은 npx 기반이므로, 설정 파일에서 command를 다르게 지정하면 됩니다.

{
  "mcpServers": {
    "my-python-server": {
      "command": "uvx",
      "args": ["python-mcp-package"]
    },
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

위와 같이 mcpServers 블록 안에 여러 서버를 나란히 등록하면 Claude Desktop이 시작 시 모두 자동으로 실행합니다.

흔한 오류와 해결 방법

”uvx: command not found” 오류

uv가 설치되지 않았거나 PATH에 등록되지 않은 경우입니다. uv를 새로 설치한 뒤 터미널을 재시작합니다. 그래도 안 된다면 echo $PATH로 uv 바이너리 경로(~/.local/bin 또는 ~/.cargo/bin)가 포함되어 있는지 확인합니다.

MCP 서버 아이콘이 채팅창에 나타나지 않는 경우

1. claude_desktop_config.json 파일의 JSON 문법이 올바른지 검사합니다. 온라인 JSON 검사기를 활용하면 편리합니다.
2. command 값이 "uvx"로 정확히 설정되어 있는지 확인합니다.
3. Claude Desktop을 완전히 종료(Cmd+Q 또는 작업 관리자에서 종료)한 뒤 다시 시작합니다.

패키지를 찾지 못하는 오류

PyPI에 해당 패키지 이름이 정확히 존재하는지 확인합니다. 서버 공식 GitHub 저장소의 README에 명시된 설치 명령을 그대로 사용하는 것이 가장 안전합니다.

특정 버전 고정이 필요한 경우

uvx는 기본적으로 최신 버전을 사용합니다. 특정 버전을 고정하려면 args에 버전을 포함합니다.

{
  "args": ["패키지명==1.2.3"]
}

자주 묻는 질문

uvx와 npx의 차이는 무엇인가요?

npx는 Node.js 생태계의 임시 실행 도구이고, uvx는 Python 생태계의 동일한 개념입니다. Python으로 작성된 MCP 서버는 uvx로, JavaScript/TypeScript 기반 서버는 npx로 실행합니다. 두 방식을 하나의 설정 파일에서 혼용할 수 있습니다.

uv를 별도로 설치해야 하나요?

네, uv는 별도 설치가 필요합니다. macOS·Linux는 curl 스크립트 한 줄로, Windows는 PowerShell 명령 한 줄로 설치할 수 있습니다. 설치 후 uvx 명령도 자동으로 사용 가능합니다.

uvx로 실행하면 가상환경을 별도로 만들지 않아도 되나요?

맞습니다. uvx는 격리된 임시 환경을 자동으로 생성해 패키지를 실행하므로, 프로젝트 가상환경을 별도로 만들거나 활성화할 필요가 없습니다.

어떤 MCP 서버가 uvx를 지원하나요?

PyPI에 배포된 Python 패키지 형태의 MCP 서버라면 기본적으로 uvx로 실행 가능합니다. 서버의 README나 설치 안내에 uvx 명령이 명시되어 있는지 확인하면 됩니다.

claude_desktop_config.json 파일이 없으면 어떻게 하나요?

Claude Desktop을 한 번이라도 실행하면 설정 파일 경로가 자동으로 생성됩니다. 파일 자체가 없다면 해당 경로에 직접 새 파일을 만들어 JSON 내용을 입력하면 됩니다.

MCP 서버 연결 후 Claude에서 바로 사용할 수 있나요?

Claude Desktop 재시작 후 채팅창 하단에 해당 MCP 서버의 도구 아이콘이 표시되면 정상 연결된 것입니다. 이후 대화에서 자연어로 기능을 요청하면 됩니다.

다음 단계

uvx 설치 방법을 익혔다면, 개발도구 카테고리에서 더 많은 Python 기반 MCP 서버를 탐색해 보세요. 한국 문서 처리 서버로는 코르독(KorDoc)(HWP·PDF·DOCX 변환), HWP-MCP(한글 문서 읽기·편집), 한포지(HwpForge)(HWPX 읽기·쓰기·변환)가 준비되어 있습니다. 아직 원하는 서버가 없다면 전체 서버 목록에서 검색하거나 새 서버를 제출해 주세요.