leerowoon.dev
Claude Desktop MCP Servers 'spawn npx ENOENT' 에러 해결

Claude Desktop MCP Servers 'spawn npx ENOENT' 에러 해결

2025년 04월 06일

#claude

#mcp

#troubleshooting

들어가기 전에

macOS, mise를 사용하는 환경에서, Claude 데스크톱 앱에 MCP Servers 설정 시 발생한 에러를 해결하는 방법을 소개합니다.

mise는 다양한 언어/툴의 버전을 관리할 수 있는 통합
버전 매니저입니다.

에러 발생

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

claude_desktop_config.json 파일에 Filesystem MCP Server를 설정하면 다음과 같은 에러가 발생했습니다.

  • Could not connect to MCP server filesystem
  • MCP filesystem: spawn npx ENOENT
  • MCP filesystem: Server disconnected. For troubleshooting guidance, please visit our debugging documentation

MCP 에러MCP 에러

에러 분석 및 원인

MCP 서버 초기화 과정에서 npx 명령어를 실행하는 데 문제가 있었습니다.
주요 에러 메시지는 spawn npx ENOENT로, 이는 npx 명령어를 찾을 수 없다는 의미입니다.

  • spawn : Node.js의 child_process.spawn() 함수로 외부 명령어 실행 시도
  • ENOENT : Error NO ENTity, 해당 파일이나 디렉토리가 존재하지 않음

저는 시스템에 npx가 설치되어 있는데 찾지 못하고 있습니다.

npx 설치 확인

which npx
/Users/roy/.local/share/mise/installs/node/22.14.0/bin/npx

$PATH 설정 확인

시스템에 $PATH도 잘 설정되어 있습니다.

echo $PATH
(생략)/Users/roy/.local/share/mise/installs/node/22.14.0/bin

원인

macOS에서 일반 GUI 애플리케이션들은 launchd 시스템을 통해 관리됩니다. launchd와 로그인 쉘(bash, zsh)이 사용하는 $PATH가 다르기 때문에 발생하는 문제입니다. launchd가 실행하는 프로세스는 로그인 쉘에서 설정한 환경 변수($PATH 포함)를 자동으로 상속받지 않습니다. launchd는 기본적으로 매우 제한된 환경 변수 세트를 사용합니다. 그래서 npx 명령어를 찾을 수 없습니다.

해결 방법

Notes on setting up Claude Desktop MCP servers 문서에 따르면 앱의 이런 동작을 보정하기 위해서 플랫폼에 따라 조회하는 몇 가지 고정 경로가 있다고 합니다.

${homeDir}/.nvm/versions/node/*/bin
/opt/homebrew/Caskroom/miniforge/base/envs/py*/bin
/usr/local/bin
/opt/homebrew/bin
/opt/local/bin
/usr/bin

/opt/homebrew/bin 경로에 npx, node 심볼릭 링크를 설정해 주고 Claude 앱을 다시 실행하면 해결됩니다.

ln -s $(mise which node) /opt/homebrew/bin/node
ln -s $(mise which npx) /opt/homebrew/bin/npx

심볼릭 링크는 아래 명령어로 삭제할 수 있습니다.

rm /opt/homebrew/bin/npx
rm /opt/homebrew/bin/node

참고 문서