Claude MCP 연결 안 될 때 바로 해결하는 4가지 방법

터미널에서는 잘 돌아가는데 왜 Claude만 켜면 멈출까

Claude Desktop에 Model Context Protocol(MCP) 서버를 연결해 로컬 컴퓨터의 파일이나 데이터베이스를 연동하려다 에러 화면을 마주하는 일이 자주 생깁니다. 터미널에서는 잘 돌아가던 스크립트가 이상하게 Claude GUI 앱에만 올라가면 먹통이 되거나, 연결 버튼 자체가 비활성화되는 경우가 있죠. 이 문제는 대부분 Claude Desktop이 로컬 사용자의 환경 변수 경로를 제대로 읽지 못할 때 발생합니다. 직접 파일 경로를 확인하고 설정 형식을 바로잡는 식으로 몇 가지만 손보면 대부분 5분 안에 해결할 수 있습니다.

오작동을 바로잡기 전에 설정 파일부터 열기

문제를 풀려면 먼저 설정 파일의 위치부터 정확히 알아야 합니다. 운영체제마다 저장 경로가 다르고 숨김 폴더 깊숙이 들어 있어서 찾기 쉽지 않거든요. Windows라면 파일 탐색기 주소창에 %APPDATA%\Claude를 입력해 바로 이동하는 방법이 편합니다. macOS 사용자라면 ~/Library/Application Support/Claude 폴더로 들어가 claude_desktop_config.json 파일을 찾아야 하죠. 이 텍스트 파일을 메모장이나 VS Code 같은 에디터로 열어 수정하는 것부터 디버깅이 시작된다고 보면 됩니다.

spawn npx ENOENT 또는 spawn node ENOENT 오류

터미널 창에서는 node나 npx 명령어가 문제없이 실행되는데 정작 Claude Desktop에서는 이 에러를 내고 멈추는 상황이 가장 흔합니다. 터미널은 로그인 시점에 사용자의 프로필에 있는 PATH 환경 변수를 읽어들이지만, GUI 앱은 그 정보가 제대로 연동되지 않기 때문입니다. 결국 실행 파일이 어디 있는지 시스템이 찾지 못해 오류가 발생하는 구조죠.

이를 고치려면 claude_desktop_config.json 설정 안의 command 항목을 단순한 npx나 node 대신 절대 경로로 바꿔 넣어야 합니다. 예를 들어 Windows에 설치된 Node.js 기본 실행 파일 경로를 찾아 그대로 대입하는 방식이 안전합니다. macOS 환경이라면 터미널에서 which node를 입력해 확인한 결과를 설정에 옮겨 적는 쪽이 안정적입니다.

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\Username\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-memory\\dist\\index.js"
      ]
    }
  }
}

Failed to parse config file 문법 오류

설정 파일을 열어 편집하다 보면 쉼표 하나를 잘못 찍거나 괄호를 닫지 않아 프로그램 자체가 로드되지 않는 문제도 자주 생깁니다. JSON 문법은 형식을 아주 엄격하게 따지거든요. 특히 마지막 요소 뒤에 남겨진 쉼표(Trailing Comma)가 골칫거리가 되기 쉽습니다.

Windows 사용자라면 파일 경로에 들어가는 백슬래시(\) 문자를 특히 신중하게 다뤄야 합니다. JSON 문자열 안에서 백슬래시는 뒤에 오는 문자를 특별하게 처리하는 이스케이프 역할을 맡기 때문에, 단일 문자 그대로 넣으면 파싱 오류가 발생합니다. 해결하려면 모든 백슬래시를 두 번 연속(\\)으로 쓰거나, 일반적인 슬래시(/) 기호로 바꿔 경로를 적어야 안정적으로 동작합니다.

// 에러가 나는 부적절한 설정 예시
"command": "C:\\Program Files\\nodejs\\node.exe"

// 이중 백슬래시를 적용해 수정한 예시
"command": "C:\\\\Program Files\\\\nodejs\\\\node.exe"

API key not found 또는 인증 환경 변수 차단 현상

GitHub API나 외부 데이터베이스에 접근하는 MCP 도구들은 각각 인증 토큰을 요구합니다. 셸 환경에서는 이미 전역 변수로 세팅해 두어서 무심코 넘어갔을 수 있지만, 데스크톱 Claude에서는 그 값을 넘겨받지 못해 바로 접속 거부 로그를 남기고 멈출 수 있습니다. 서버 파일 경로가 아무리 정확해도 인증 단계에서 막히면 결국 연결이 성립되지 않죠.

이럴 때는 설정 파일 안에 서버별로 env 블록을 명시적으로 넣어 주는 방법이 필요합니다. 외부 시스템 환경 변수에 기대지 않고, Claude가 실행되면서 생기는 내부 프로세스에 직접 주입하는 방식입니다. 아래처럼 args 목록 바로 아래에 env 설정을 둬 고유 키값을 매핑하면 외부 API 서버와 정상적으로 연결할 수 있습니다.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_your_key_here"
      }
    }
  }
}

설정 변경 후에도 무반응이거나 아이콘이 안 보일 때

모든 설정을 올바르게 입력했는데도 화면 우측 아래에 번개 모양 플러그인 단추가 나타나지 않거나 회색으로 고정되어 있다면, 파일은 바뀌었지만 메모리에 떠 있는 기존 프로세스가 계속 살아 있는 경우가 많습니다. 새 설정이 반영되지 않은 채 기존 상태만 유지되면 화면상으로는 아무 변화가 없는 것처럼 보이거든요. 확실하게 반영하려면 메인 화면 창만 닫을 게 아니라 백그라운드 작업까지 완전히 종료한 뒤 다시 실행해야 합니다.

Windows를 쓴다면 화면 하단 오른쪽 시스템 트레이에서 Claude 아이콘을 마우스 오른쪽 버튼으로 클릭한 뒤 Quit 버튼을 직접 눌러 종료해야 합니다. macOS 역시 단축키 Cmd + Q를 활용해 실행 흐름을 통째로 정리하는 편이 좋죠. 이렇게 다시 켜야 수정한 설정 내용을 제대로 읽기 시작합니다. 그래도 계속 먹통이라면 아래 디렉터리에서 mcp.log나 관련 서버 이름이 붙은 텍스트 파일을 열어 어떤 이유로 막혔는지 확인해 보세요.

Claude Desktop 없이 단독으로 에러를 잡아내는 법

설정 변경이나 경로 확인을 마쳤는데도 계속 통신이 엇갈린다면 Anthropic에서 배포하는 mcp-inspector 디버깅 도구를 써 보는 것이 좋습니다. 이 도구는 실제 GUI 앱을 통하지 않고 터미널 안에서 MCP 서버가 명령어를 잘 받아들이는지 그대로 검사할 수 있습니다. 연결이 어디서 끊어졌는지 바로 확인할 수 있어서, 엉뚱한 설정을 붙잡고 시간을 낭비하지 않게 도와줍니다.

터미널에 아래 검사 명령을 입력해 실행하면 곧장 브라우저에 가상의 관리자 콘솔이 열립니다. 콘솔에서 정의해 둔 도구 목록을 호출해 보고, 내부 리턴 값이 깔끔하게 넘어오는지 확인하면 원인을 빠르게 가늠할 수 있습니다.

npx -y @modelcontextprotocol/inspector node path/to/server/index.js

구축해 둔 로컬 도구들과 원활하게 소통하려면

결국 MCP 서버가 안 켜지는 상황의 대부분은 백그라운드 환경 변수의 장벽이나 단순한 기호 오타에서 시작됩니다. 초반에 연결 에러 때문에 진입장벽을 느껴 중간에 포기하기보다는, 파일 경로를 꼼꼼하게 다듬고 에러 메시지를 차근차근 확인하면서 구조를 잡는 편이 결과적으로 로컬 AI 에이전트 환경의 효용을 크게 높여 줍니다. 손수 정리한 연동 경로 하나가 앞으로 매일 반복할 귀찮은 수작업을 한 번에 줄여줄 수 있기 때문입니다.