M MCP모아
FAQ

Claude MCP 연결 안될 때 해결법 — 오류 원인별 트러블슈팅 가이드

Claude Desktop·Claude Code에서 MCP 서버 연결 안될 때 원인별 해결법을 단계별로 정리했습니다. claude_desktop_config 오류, 망치 아이콘 없음, 서버 크래시 등 실전 트러블슈팅.

Claude Desktop에서 MCP 서버 연결 오류를 해결하는 트러블슈팅 가이드 표지 이미지

Claude Desktop이나 Claude Code에서 MCP 서버 연결이 안 될 때, 원인 대부분은 설정 파일의 JSON 문법 오류, 경로 문제, 또는 런타임 미설치 세 가지 중 하나입니다. 이 가이드는 오류 원인별로 체크리스트와 해결 방법을 제공하며, 읽고 나면 대부분의 MCP 연결 문제를 직접 해결할 수 있습니다.

MCP 연결이 왜 안 되는 걸까요?

MCP(Model Context Protocol)는 Claude가 외부 도구와 통신하는 표준 규격입니다. Claude Desktop은 실행 시 claude_desktop_config.json을 읽어 등록된 MCP 서버를 자동으로 실행합니다. 이 과정에서 문제가 생기면 망치 아이콘(도구 메뉴)이 나타나지 않거나, 특정 서버만 빠져 있거나, 연결이 간헐적으로 끊기는 증상이 생깁니다.

아래 표는 자주 나타나는 증상과 원인을 정리한 것입니다.

증상주요 원인
망치 아이콘 자체가 없음config 파일 위치 오류 또는 JSON 문법 오류
망치는 있지만 서버가 0개설정 파일 내 mcpServers 항목 누락 또는 잘못된 키 이름
특정 서버만 연결 안 됨해당 런타임(node, python, uvx 등) 미설치 또는 경로 오류
처음엔 됐다가 끊김서버 프로세스 크래시, 메모리 부족, API 키 오류
설정 바꿔도 반영 안 됨Claude Desktop 재시작 안 함

1단계: 설정 파일 위치 확인

설정 파일이 정확한 위치에 없으면 Claude Desktop은 MCP를 아예 인식하지 못합니다.

macOS:

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

Windows:

%APPDATA%\Claude\claude_desktop_config.json

파일이 없다면 직접 생성해야 합니다. 아래가 최소 유효한 구조입니다.

{
  "mcpServers": {}
}

파일을 생성하거나 수정한 뒤에는 반드시 Claude Desktop을 완전히 종료(시스템 트레이까지 종료)하고 재시작해야 변경이 반영됩니다.

2단계: JSON 문법 오류 잡기

Claude MCP 연결 실패 원인 중 가장 흔한 것이 JSON 문법 오류입니다. 쉼표 하나, 따옴표 하나가 잘못돼도 전체 설정이 무시됩니다.

흔한 실수 유형:

실수 유형잘못된 예올바른 예
마지막 항목 뒤 쉼표"key": "val", (마지막)"key": "val"
작은따옴표 사용'command': 'npx'"command": "npx"
Windows 경로 백슬래시"C:\Users\...""C:\\Users\\..."
숫자를 문자열로"port": "3000""port": 3000

검증 방법: 터미널에서 아래 명령으로 JSON 문법을 바로 확인할 수 있습니다.

# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

오류가 없으면 파싱된 JSON이 그대로 출력됩니다. 오류가 있으면 몇 번째 줄인지 알려줍니다.

3단계: 런타임과 경로 확인

MCP 서버는 보통 Node.js(npx), Python(uvx), 또는 직접 실행 파일로 구동됩니다. Claude Desktop이 서버를 실행하려면 해당 런타임이 설치되어 있고 PATH에 등록되어 있어야 합니다.

# Node.js 설치 확인
node --version
npx --version

# Python/uvx 확인
python3 --version
uvx --version

중요: Claude Desktop은 일반 터미널과 다른 환경 변수를 사용할 수 있습니다. 특히 macOS에서 Homebrew로 설치한 Node.js가 터미널에서는 잘 되지만 Claude Desktop에서는 인식 안 되는 경우가 있습니다. 이럴 때는 설정 파일에서 command에 절대 경로를 지정하는 것이 확실합니다.

# node 절대 경로 확인
which node
# 예시 출력: /opt/homebrew/bin/node
{
  "mcpServers": {
    "my-server": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/절대/경로/server.js"]
    }
  }
}

4단계: 로그로 정확한 오류 파악하기

증상만으로 원인을 파악하기 어렵다면 로그 파일이 정답을 갖고 있습니다.

macOS 로그 위치:

~/Library/Logs/Claude/

이 폴더 안에 mcp-server-[서버이름].log 형태의 파일이 있습니다. 터미널에서 실시간으로 확인하려면:

tail -f ~/Library/Logs/Claude/mcp*.log

Windows 로그 위치:

%APPDATA%\Claude\logs\

로그에서 흔히 보이는 오류 메시지와 해결법:

오류 메시지해결 방법
command not found런타임 설치 또는 절대 경로 지정
ENOENT파일/디렉터리 경로 오류 확인
EACCES실행 파일 권한 문제 (chmod +x)
JSON parse errorconfig 파일 문법 재검토
Connection refused서버가 실행됐지만 포트 문제

5단계: npx 기반 서버 설정 예시

MCP모아에 등록된 한국어 MCP 서버 대부분은 npx -y 방식으로 설치합니다. 아래는 실제 동작하는 설정 예시입니다.

코르독(KorDoc) — HWP·PDF·DOCX를 Markdown으로 변환:

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    }
  }
}

HWP-MCP — 한글 문서 읽기·편집:

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

한포지(HwpForge) — HWPX 문서 AI 에이전트 연동:

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

여러 서버를 동시에 등록할 때는 mcpServers 객체 안에 나란히 추가하면 됩니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

Claude Code(CLI)에서 MCP 연결 안 될 때

Claude Code(터미널 CLI 버전)는 설정 방식이 다릅니다. claude_desktop_config.json을 보지 않고, 아래 명령으로 MCP를 등록합니다.

# MCP 서버 추가
claude mcp add 서버이름 -- npx -y 패키지명

# 등록된 서버 목록 확인
claude mcp list

# 특정 서버 제거
claude mcp remove 서버이름

Claude Code에서 연결이 안 된다면 claude mcp list로 서버가 올바르게 등록됐는지 먼저 확인하세요.

데이터 흐름 구조

MCP 연결이 어떻게 이루어지는지 흐름을 이해하면 문제 지점을 더 쉽게 찾을 수 있습니다.

Claude Desktop/Code
      |
      | (1) claude_desktop_config.json 읽기
      v
  설정 파싱 (JSON 오류 → 여기서 실패)
      |
      | (2) command + args로 서버 프로세스 실행
      v
  런타임 실행 (node not found → 여기서 실패)
      |
      | (3) stdio / MCP 프로토콜로 통신
      v
  MCP 서버 (서버 크래시 → 여기서 실패)
      |
      | (4) 외부 서비스·파일시스템 접근
      v
  결과를 Claude에게 반환

각 단계에서 어디서 막혔는지 로그로 확인하면 원인을 훨씬 빠르게 찾을 수 있습니다.

흔한 오류와 즉시 해결법 요약

증상체크 순서
아무것도 안 보임① 파일 위치 ② JSON 문법 ③ 재시작
특정 서버만 없음① 런타임 설치 ② 절대경로 ③ 로그 확인
간헐적 끊김① 로그 오류 확인 ② 서버 GitHub Issues
설정 바꿔도 안 됨Claude Desktop 완전 재시작

자주 묻는 질문

Claude Desktop에서 망치 아이콘(MCP 도구)이 전혀 보이지 않아요.

claude_desktop_config.json 파일 위치와 JSON 문법이 올바른지 먼저 확인하세요. macOS는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows는 %APPDATA%\Claude\claude_desktop_config.json입니다. JSON 파서로 문법 오류를 잡은 뒤 Claude Desktop을 완전히 재시작하면 대부분 해결됩니다.

설정 파일은 맞는 것 같은데 특정 MCP 서버만 연결이 안 됩니다.

해당 서버의 실행 바이너리(node, npx, uvx 등)가 PATH에 있는지 확인하세요. 터미널에서 직접 install_cmd를 실행해 보고 오류 메시지를 확인하는 것이 가장 빠른 진단 방법입니다. Claude Desktop 로그(~/Library/Logs/Claude/)도 함께 살펴보세요.

MCP 서버가 처음엔 됐는데 갑자기 연결이 끊겼어요.

서버 프로세스가 크래시했을 가능성이 높습니다. Claude Desktop을 재시작하면 서버도 함께 재시작됩니다. 반복적으로 끊긴다면 로그에서 오류 메시지를 확인하고, 해당 서버의 GitHub Issues를 검색해 보세요.

JSON 설정 파일에서 경로를 어떻게 적어야 하나요? 백슬래시 오류가 납니다.

Windows에서는 JSON 내 경로에 백슬래시를 두 번 써야 합니다(예: C:\\Users\\...). 또는 슬래시(/)를 사용하면 더 안전합니다. macOS·Linux에서는 슬래시(/)를 그대로 사용합니다.

npx로 설치하면 매번 다운로드가 발생해 느려요. 빠르게 하는 방법이 있나요?

npx -y 옵션은 패키지를 매번 최신 버전으로 내려받습니다. 로컬에 미리 설치하려면 npm install -g 패키지명으로 전역 설치한 뒤 command를 npx 대신 패키지 바이너리 경로로 바꾸세요. 단, 최신 버전 추적이 필요하다면 npx -y가 더 편리합니다.

Claude Code(터미널 CLI)와 Claude Desktop의 MCP 설정 방식이 다른가요?

네, 다릅니다. Claude Desktop은 claude_desktop_config.json 파일로 MCP를 설정하고, Claude Code(CLI)는 claude mcp add 명령어 또는 프로젝트별 .claude/settings.json으로 관리합니다. 각 환경에 맞는 방법을 사용해야 합니다.

다음 단계

연결 문제를 해결했다면 실제로 유용한 MCP 서버를 추가해 보세요. 한국어 문서 처리에 특화된 코르독(KorDoc), HWP-MCP, 한포지(HwpForge)는 별도 API 키 없이 npx 한 줄로 바로 시작할 수 있습니다. 더 많은 한국 특화 MCP 서버는 개발도구 카테고리와 전체 서버 목록에서 찾아볼 수 있습니다.

이 글과 관련된 MCP 서버