Claude MCP 설정 오류 해결: server failed to start, command not found, permission denied 점검 순서

Claude MCP 서버가 실행되지 않을 때는 설정 파일, 명령어 경로, Node.js, 권한 순서로 확인합니다.

Claude MCP 설정 오류는 대부분 설정 파일 위치, JSON 문법, Node.js와 npx 경로, 파일 접근 권한에서 발생합니다. MCP server failed to start, command not found, permission denied, spawn npx ENOENT가 보이면 먼저 터미널에서 MCP 서버 명령어가 직접 실행되는지 확인해야 합니다.

Claude Desktop이나 Claude Code 안에서만 오류를 보면 원인을 좁히기 어렵습니다. 같은 명령어를 macOS 터미널이나 Windows PowerShell에서 실행해 보고, 터미널에서도 실패하면 Claude 설정 문제가 아니라 로컬 실행 환경 문제부터 고치는 순서가 좋습니다.

자주 보이는 Claude MCP 오류 메시지

MCP 서버 연결 문제는 오류 문구가 조금씩 다르게 표시될 수 있습니다. 아래 메시지는 모두 설정 파일, 명령어 경로, 실행 권한, 인증 값, 서버 종료 문제와 연결해서 확인해야 합니다.

언제 발생하는 오류인지

Claude MCP 서버 오류는 Claude Desktop에 MCP 설정을 추가했는데 도구가 보이지 않을 때 자주 발생합니다. Claude Code에서 MCP 서버를 추가했지만 실행되지 않거나, claude mcp list에는 보이는데 실제 세션에서 사용할 수 없을 때도 같은 흐름으로 점검합니다.

• Claude Desktop MCP 설정 후 도구가 보이지 않을 때
• Claude Code에서 MCP 서버를 추가했는데 실행되지 않을 때
• npx 기반 MCP 서버를 설정했는데 Claude가 명령어를 찾지 못할 때
• Notion, Google Sheets, GitHub, 파일 시스템 MCP 서버를 연결할 때
• API 키나 토큰을 넣었는데 서버가 바로 끊길 때

Claude MCP 설정 오류의 주요 원인 5가지

오류를 빠르게 줄이려면 원인을 넓게 보지 말고 5가지로 나눠 확인하는 편이 좋습니다. Claude 앱 자체 문제로 보기 전에 로컬 명령어 실행 여부를 먼저 확인하면 시간을 줄일 수 있습니다.

1. MCP 설정 파일 위치가 잘못되었습니다.
2. JSON 형식에 쉼표, 따옴표, 중괄호 오류가 있습니다.
3. node 또는 npx가 Claude 실행 환경에서 잡히지 않습니다.
4. 서버 명령어가 터미널에서도 실행되지 않습니다.
5. 파일 접근 권한 또는 실행 권한이 부족합니다.

빠른 점검 순서

아래 순서대로 확인하면 원인을 단계별로 좁힐 수 있습니다. 중간에 성공한 단계가 나오면 바로 Claude를 재시작해 도구 표시 여부를 확인합니다.

1. Claude Desktop 또는 Claude Code를 완전히 종료한 뒤 다시 실행합니다.
2. MCP 설정 파일 위치가 맞는지 확인합니다.
3. JSON 문법 오류가 없는지 확인합니다.
4. node -v, npm -v, npx -v로 실행 환경을 확인합니다.
5. MCP 서버 명령어를 터미널에서 직접 실행합니다.
6. 권한 오류가 나오면 파일 실행 권한과 폴더 접근 권한을 확인합니다.
7. Claude에서 도구가 표시되는지 확인합니다.

node -v
npm -v
npx -v

Claude Code를 사용한다면 설정된 MCP 서버 목록과 상태도 함께 확인합니다.

claude mcp list
claude mcp get 서버이름

Claude Code 세션 안에서는 아래 명령으로 MCP 연결 상태를 확인할 수 있습니다.

/mcp

macOS에서 확인할 것

macOS에서는 터미널에서 npx가 잘 실행되더라도 Claude Desktop 같은 GUI 앱에서는 PATH가 다르게 잡힐 수 있습니다. 특히 Homebrew, nvm, asdf로 Node.js를 설치한 경우 이 차이가 자주 발생합니다.

Claude Desktop 설정 파일 위치 예시

Claude Desktop의 MCP 설정을 직접 편집한다면 아래 위치를 먼저 확인합니다.

~/Library/Application Support/Claude/claude_desktop_config.json

파일이 없다면 새로 만들 수 있지만, 기존 설정이 있는지 먼저 확인하는 편이 좋습니다.

ls -la "$HOME/Library/Application Support/Claude"

node와 npx 경로 확인

터미널에서 아래 명령어를 실행해 실제 경로를 확인합니다.

which node
which npm
which npx
echo $PATH

Apple Silicon Mac에서 Homebrew로 설치했다면 /opt/homebrew/bin/npx가 나올 수 있습니다. Intel Mac이나 공식 설치 패키지를 사용했다면 /usr/local/bin/npx가 나올 수 있습니다.

npx 절대 경로를 설정 파일에 넣는 예시

spawn npx ENOENT가 나오면 Claude가 npx라는 명령어를 찾지 못한 것입니다. 이때는 command에 npx 대신 절대 경로를 넣어 확인합니다.

{
  "mcpServers": {
    "sample-server": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "mcp-server-package-name", "server-arg"]
    }
  }
}

위 예시는 구조 확인용입니다. 실제 패키지명과 인자는 연결하려는 MCP 서버 문서에 맞게 바꿔야 합니다.

Windows에서 확인할 것

Windows에서는 Node.js 설치 여부와 PATH 반영 여부를 PowerShell에서 먼저 확인합니다. Node.js를 방금 설치했다면 Claude와 PowerShell을 모두 새로 열어야 경로가 반영되는 경우가 많습니다.

PowerShell에서 Node.js와 npx 확인

node -v
npm -v
npx -v

명령어가 잡히지 않으면 실제 실행 파일 위치를 확인합니다.

where.exe node
where.exe npm
where.exe npx

Windows 설정 파일 위치 예시

Claude Desktop 설정 파일은 사용자 AppData 경로에서 확인합니다.

%APPDATA%\Claude\claude_desktop_config.json

PowerShell에서는 아래처럼 열어볼 수 있습니다.

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Windows에서 npx 절대 경로를 쓰는 예시

PATH가 꼬였거나 Claude에서만 npx를 찾지 못한다면 npx.cmd 절대 경로로 테스트합니다.

{
  "mcpServers": {
    "sample-server": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "mcp-server-package-name", "server-arg"]
    }
  }
}

경로에 공백이 있어도 JSON 문자열 안에서는 전체 경로를 하나의 문자열로 넣습니다. Windows 경로의 역슬래시는 \\처럼 두 번 적어야 합니다.

command not found와 spawn npx ENOENT 해결

command not found는 터미널이 명령어를 찾지 못한다는 뜻입니다. spawn npx ENOENT는 Claude가 MCP 서버를 실행하려고 했지만 npx 실행 파일을 찾지 못했다는 뜻으로 볼 수 있습니다.

터미널에서 직접 실행

설정 파일에 넣은 명령어를 먼저 터미널에서 실행합니다. 아래 예시는 구조 확인용입니다.

npx -y mcp-server-package-name server-arg

터미널에서 패키지 설치 안내, 인증 오류, 인자 오류가 나오면 Claude 설정으로 넘기기 전에 해당 오류를 먼저 처리합니다.

nvm 사용자는 실행 환경 차이를 확인

nvm으로 Node.js를 설치하면 터미널을 열 때만 Node.js 경로가 설정되는 경우가 있습니다. Claude Desktop은 GUI 앱이라 셸 초기화 파일을 그대로 읽지 않을 수 있습니다.

which npx
node -p "process.execPath"

위 결과를 보고 Claude 설정 파일의 command에 절대 경로를 넣어 테스트하면 PATH 문제인지 빠르게 확인할 수 있습니다.

Claude Code에서 stdio 서버를 추가하는 예시

Claude Code에서는 -- 뒤에 실제 서버 실행 명령어를 넣습니다. 서버 옵션이 Claude Code 옵션으로 해석되지 않게 나누는 역할입니다.

claude mcp add --transport stdio sample-server -- npx -y mcp-server-package-name server-arg

permission denied 해결

permission denied는 명령어가 있어도 실행할 권한이 없거나, MCP 서버가 접근하려는 파일과 폴더 권한이 부족할 때 발생합니다. 파일 시스템 MCP 서버를 사용할 때 특히 자주 확인해야 합니다.

실행 파일 권한 확인

macOS나 Linux에서 로컬 스크립트를 직접 실행하는 MCP 서버라면 실행 권한을 확인합니다.

ls -la ./mcp-server

주의: 실행 권한을 바꾸기 전에 파일이 신뢰할 수 있는 서버 파일인지 확인하세요. 출처를 모르는 파일에 실행 권한을 주면 위험할 수 있습니다.

chmod +x ./mcp-server

chmod 777처럼 모든 사용자에게 쓰기 권한을 여는 방식은 피하는 편이 좋습니다. 필요한 실행 권한만 좁게 부여합니다.

파일 시스템 접근 권한 확인

파일 시스템 MCP 서버는 지정한 폴더만 접근하도록 제한하는 것이 안전합니다. 홈 폴더 전체나 시스템 폴더를 넓게 열기보다 작업에 필요한 폴더만 지정합니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "mcp-server-package-name", "/Users/yourname/Documents/mcp-workspace"]
    }
  }
}

macOS에서는 시스템 설정의 개인정보 보호 및 보안 항목에서 Claude의 파일 접근 권한이 제한되어 있을 수 있습니다. Windows에서는 관리자 권한, 조직 보안 정책, 백신 또는 보안 소프트웨어가 실행을 막는지도 확인합니다.

JSON 설정 오류 점검

MCP 설정 파일은 JSON 형식이므로 쉼표 하나가 빠져도 서버가 로드되지 않을 수 있습니다. 특히 command와 args를 한 줄 문자열처럼 섞어 쓰는 실수가 많습니다.

올바른 command와 args 구분

command에는 실행 파일만 넣고, 나머지 옵션은 args 배열에 나눠 넣는 방식이 안전합니다.

{
  "mcpServers": {
    "sample-server": {
      "command": "npx",
      "args": ["-y", "mcp-server-package-name", "--option", "value"]
    }
  }
}

자주 틀리는 JSON 예시

아래처럼 명령어 전체를 command에 한 번에 넣으면 실행 환경에 따라 실패할 수 있습니다.

{
  "mcpServers": {
    "sample-server": {
      "command": "npx -y mcp-server-package-name --option value"
    }
  }
}

macOS에서 JSON 문법 확인

python3 -m json.tool "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Windows PowerShell에서 JSON 문법 확인

Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" -Raw | ConvertFrom-Json

쉼표 누락, 따옴표 오류, 중괄호 닫힘 오류, Windows 경로의 역슬래시 처리 오류가 나면 먼저 JSON을 고친 뒤 Claude를 다시 실행합니다.

MCP 서버 권한과 보안 주의점

MCP 서버는 로컬 파일, 외부 API, GitHub 저장소, 업무 계정 데이터에 접근할 수 있습니다. 오류 해결만 보고 권한을 넓게 열면 나중에 더 큰 문제가 될 수 있습니다.

• 읽기 권한과 쓰기 권한을 구분합니다.
• 파일 시스템 서버는 필요한 폴더만 허용합니다.
• API 키는 공개 저장소에 커밋하지 않습니다.
• 자동 실행 도구는 승인 흐름을 둡니다.
• 출처가 불명확한 MCP 서버는 연결하지 않습니다.

도구가 표시되지 않는 문제를 해결한 뒤에는 실제로 Claude가 어떤 파일과 API에 접근할 수 있는지 다시 확인하는 것이 좋습니다. 오류 해결과 권한 설계는 함께 봐야 합니다.

공식 자료로 더 확인하기

Claude MCP 설정은 Claude Desktop, Claude Code, MCP 서버 종류, Node.js 설치 방식에 따라 달라질 수 있습니다. 설정 예시를 그대로 복사하기 전에 공식 문서에서 현재 권장 방식과 서버별 요구 조건을 확인하는 것이 좋습니다.

함께 보면 좋은 글

자주 묻는 질문

Claude MCP 오류는 설정 파일보다 먼저 터미널에서 같은 서버 명령어가 실행되는지 확인하면 원인을 가장 빠르게 좁힐 수 있습니다.