[AI 실전] MCP 트러블슈팅 - 4가지 이슈 및 해결 방법

1. spawn ENOENT / Database file not found

• 🚨 현상:
  • spawn ENOENT 에러 발생
  • Database file not found 에러 발생
  • Claude Desktop이 MCP Server를 실행하지 못함
• 🚒 원인:
  • MCP 설정 JSON에서 ~(틸트) 경로를 인식하지 못함
  • 상대 경로(./products.db) 사용 시 Claude Desktop 실행 위치와 불일치
  • GUI 애플리케이션은 쉘의 홈 디렉토리(~)를 인식하지 못함
• ✅ 해결:
  • /Users/username/... 처럼 절대 경로(Absolute Path)로 변경
  • DB 파일의 절대 경로 확인 후 설정 파일에 반영

에러 로그:

# Claude Desktop 로그에서 확인
spawn ENOENT
Database file not found: ~/projects/mcp-practice/products.db

수정 전 (설정 파일):

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "~/projects/mcp-practice/products.db"  // ❌ 틸트 경로
      ]
    }
  }
}

수정 후 (설정 파일):

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/username/projects/mcp-practice/products.db"  // ✅ 절대 경로
      ]
    }
  }
}

절대 경로 확인 명령어:

# 현재 디렉토리에서 절대 경로 확인
cd ~/projects/mcp-practice
realpath products.db
# /Users/username/projects/mcp-practice/products.db

# 또는
pwd
# /Users/username/projects/mcp-practice
# + "/products.db" = 절대 경로

---

2. uvx: command not found

• 🚨 현상:
  • uvx: command not found 에러 발생
  • 터미널에서 uvx 명령어 실행 시 명령어를 찾을 수 없음
• 🚒 원인:
  • PATH 환경변수에 uv가 등록되지 않음
  • UV 설치 스크립트가 PATH 자동 등록 실패 (권한 문제)
  • Mac은 zsh가 기본 쉘인데 .bash_profile에만 PATH 추가 시도
• ✅ 해결:
  • export PATH=$PATH:... 설정 추가
  • .zshrc 파일에 PATH 영구 등록
  • 또는 brew install uv 재설치

에러 로그:

$ uvx --version
zsh: command not found: uvx

해결 방법 1: PATH 수동 추가 (임시)

# zsh 사용자 (Mac 기본 쉘)
source $HOME/.local/bin/env

# 확인
uvx --version
# uvx 0.9.17

해결 방법 2: .zshrc에 영구 등록 (권장)

# .zshrc에 PATH 추가
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# 설정 적용
source ~/.zshrc

# 확인
uvx --version
# uvx 0.9.17

해결 방법 3: Homebrew로 재설치

# Homebrew로 설치 (PATH 자동 등록)
brew install uv

# 확인
uvx --version
# uvx 0.9.17

---

3. JSON Syntax Error

• 🚨 현상:
  • Claude Desktop 앱이 실행되자마자 죽거나, 설정 파일 로드 실패
  • JSON 파싱 에러 발생
• 🚒 원인:
  • JSON 파일의 마지막 콤마(,) 실수
  • 괄호 짝 안 맞음
  • 따옴표 누락 또는 잘못된 이스케이프
• ✅ 해결:
  • JSON Validator 사이트에서 문법 검사
  • 마지막 콤마 제거
  • 괄호 짝 확인

에러 로그:

# Claude Desktop 로그에서 확인
Error parsing JSON: Unexpected token } in JSON at position 123

수정 전 (설정 파일 - 마지막 콤마 오류):

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/username/projects/mcp-practice/products.db"
      ]
    },  // ❌ 마지막 항목 뒤에 콤마
  }
}

수정 후 (설정 파일):

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/username/projects/mcp-practice/products.db"
      ]
    }  // ✅ 마지막 콤마 제거
  }
}

JSON 문법 검사 명령어:

# Python으로 JSON 검사
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# 출력: 정상이면 JSON이 포맷되어 출력됨
# 에러: SyntaxError 발생 시 에러 위치 표시

온라인 JSON Validator:

• https://jsonlint.com/
• https://jsonformatter.org/

---

4. Connection Refused / 도구를 사용할 수 없습니다

• 🚨 현상:
  • AI가 “도구를 사용할 수 없습니다”라고 답변
  • MCP Server 연결 실패
  • Claude Desktop 하단에 🔌 아이콘이 보이지 않음
• 🚒 원인:
  • MCP 서버 프로세스가 비정상 종료됨 (Zombie Process)
  • 이전 MCP Server 프로세스가 남아있음
  • Claude Desktop 재시작 시 이전 프로세스와 충돌
• ✅ 해결:
  • pkill -f mcp-server로 프로세스 정리 후 재시작
  • Claude Desktop 완전 종료 후 재실행

에러 로그:

# Claude Desktop 로그에서 확인
Connection refused: MCP Server process not found

해결 방법 1: 프로세스 정리 후 재시작

# MCP Server 프로세스 종료
pkill -f mcp-server

# 프로세스 확인 (종료되었는지 확인)
ps aux | grep mcp-server
# 아무것도 출력되지 않으면 정상 종료

# Claude Desktop 재시작
# Cmd + Q (완전 종료)
open -a "Claude"

해결 방법 2: 강제 종료 후 재시작

# 모든 Claude 관련 프로세스 종료
pkill -9 -f Claude

# MCP Server 프로세스도 함께 종료
pkill -f mcp-server

# 재시작
open -a "Claude"

프로세스 확인 명령어:

# 실행 중인 MCP Server 프로세스 확인
ps aux | grep mcp-server

# 출력 예시:
# username  12345  ...  uvx mcp-server-sqlite ...
# → 프로세스가 실행 중이면 종료 필요

---

참고 자료

• MCP 공식 문서: https://modelcontextprotocol.io/
• UV 공식 문서: https://docs.astral.sh/uv/
• JSON Validator: https://jsonlint.com/