Claude

클로드 MCP 서버 NPX 오류 해결하기: 절대 경로로 환경 문제 극복하기

Chan

13 Mar 2025 — 6 min read

MCP 서버 NPX 오류의 원인

여러분, 클로드 데스크탑에서 MCP 서버를 설정하려다 �낯선 오류를 만난 적 있으신가요? 저도 그랬어요. 며칠 전, 밤늦게 클로드의 MCP 기능을 설정하려다 머리를 쥐어뜯을 뻔했습니다. 특히 npx 명령어를 사용할 때 자꾸만 오류가 발생했는데... 뭐랄까, 정말 짜증났어요.

알고 봤더니 원인은 의외로 단순했습니다. 클로드 데스크탑이 사용하는 쉘(shell) 환경과 우리가 평소에 사용하는 터미널 환경이 달라서 생기는 문제였어요. 특히 Node.js와 npm 경로를 찾는 방식에서 차이가 있었죠.

"이 문제의 핵심은 경로(path) 설정입니다. 클로드 데스크탑은 시스템 환경변수를 다르게 해석하거나 아예 접근하지 못하는 경우가 있어요." - Reddit 사용자 댓글

클로드 데스크탑과 사용자 환경의 차이점

클로드 데스크탑이 실행되는 환경과 우리가 일반적으로 사용하는 터미널 환경 사이에는 몇 가지 중요한 차이점이 있습니다.

환경변수 접근 방식이 다름
Node.js 설치 경로를 찾는 메커니즘 차이
nvm이나 다른 버전 관리자를 통해 설치한 경우 경로 문제가 더 복잡해짐
권한 설정의 차이

특히 맥OS나 리눅스 환경에서 fish나 zsh 같은 쉘을 사용하거나, Windows에서 특정 환경을 설정한 경우 이런 문제가 자주 발생합니다. 솔직히 저는 맥에서 brew로 Node.js를 설치했다가 나중에 nvm으로 바꾸면서 이 문제를 겪었어요.

⚠️ 주의

nvm(Node Version Manager), asdf, volta 등의 버전 관리 도구를 사용하는 경우 문제가 더 자주 발생합니다. 이런 도구들은 Node.js 바이너리를 비표준 위치에 설치하기 때문입니다.

절대 경로를 활용한 해결 방안

이 문제의 가장 효과적인 해결책은 절대 경로(absolute path)를 사용하는 것입니다. 상대 경로나 환경변수에 의존하는 대신, Node.js와 npm 실행 파일의 정확한 위치를 지정해주는 거예요.

먼저 터미널에서 Node.js와 npm의 정확한 위치를 찾아야 합니다:

# macOS/Linux에서 Node.js 위치 찾기
which node
which npm
which npx

# Windows에서 Node.js 위치 찾기
where node
where npm
where npx

이제 이 절대 경로를 사용해서 MCP 서버를 실행하는 명령을 만들어봅시다:

# 예: macOS에서 절대 경로 사용 예시
/Users/yourusername/.nvm/versions/node/v18.15.0/bin/npx -y @modelcontextprotocol/server-brave-search

아마 좀 복잡해 보이죠? 하지만 이렇게 하면 클로드 데스크탑이 정확한 Node.js 환경을 사용할 수 있게 됩니다.

📝 메모

절대 경로를 사용할 때는 실제 사용자 이름과 정확한 Node.js 버전으로 경로를 수정해야 합니다. 위 예시는 단지 참고용일 뿐이에요.

트러블슈팅 단계별 가이드

자, 이제 실제로 문제를 해결하는 단계를 하나씩 살펴볼게요:

터미널을 열고 Node.js, npm, npx의 정확한 위치 확인
해당 경로를 복사해두기
클로드 데스크탑에서 MCP 서버 설정 화면으로 이동
명령어 입력 필드에 절대 경로를 포함한 전체 명령어 입력
연결 테스트 진행

Reddit 사용자의 실제 해결 사례를 보면, 원래는 이런 명령어를 사용했어요:

npx -y @modelcontextprotocol/server-brave-search

하지만 절대 경로를 사용해 다음과 같이 바꾸니 문제가 해결됐다고 합니다:

/home/username/.nvm/versions/node/v18.17.1/bin/npx -y @modelcontextprotocol/server-brave-search

진짜 효과가 있었어요!

Q Windows에서도 같은 방법이 적용될까요?

Windows 환경에서도 절대 경로 방식이 작동하나요?

A 네, 비슷한 원리로 적용됩니다

Windows에서는 경로 형식이 다르지만 원리는 같습니다. 예를 들어: C:\Users\Username\AppData\Roaming\nvm\v16.14.0\npx.cmd -y @modelcontextprotocol/server-brave-search 형태로 사용할 수 있습니다.