M MCP모아
FAQ

Claude MCP 설정 초기화 방법 — 서버 삭제·재설정 트러블슈팅 정리

잘못 등록한 MCP 서버를 claude mcp remove 명령 또는 claude_desktop_config.json 직접 편집으로 완전히 삭제하고 초기화하는 방법을 단계별로 정리했습니다.

Claude Desktop 설정 파일에서 MCP 서버를 삭제하고 초기화하는 방법을 안내하는 표지 이미지

MCP 서버를 잘못 등록했거나 더 이상 필요 없는 서버가 Claude 시작 시 오류를 일으킨다면, claude mcp remove 명령 또는 claude_desktop_config.json 직접 편집으로 깔끔하게 제거할 수 있습니다. 이 글에서는 두 가지 방법을 모두 설명하고, 삭제 후에도 문제가 이어질 때의 해결책까지 단계별로 안내합니다.

MCP 서버 설정이 꼬이는 이유

MCP(Model Context Protocol) 서버는 Claude Desktop이나 Claude Code CLI에 외부 도구를 연결해 주는 플러그인 역할을 합니다. 서버 하나가 잘못 등록되면 다음과 같은 증상이 나타납니다.

  • Claude Desktop 실행 시 “MCP 서버에 연결할 수 없음” 오류 팝업
  • Claude Code에서 특정 명령 실행 중 프로세스 중단
  • 테스트 목적으로 등록한 서버가 계속 실행돼 리소스 낭비

근본 원인은 대부분 세 가지입니다.

원인증상해결 방향
패키지 경로 오타서버 시작 실패 메시지경로 수정 또는 서버 제거
더 이상 유지되지 않는 패키지버전 없음 오류서버 제거 후 대안 설치
API 키 미설정 상태로 등록인증 오류 반복키 추가 또는 서버 제거

방법 1 — claude mcp remove 명령 사용 (Claude Code CLI)

Claude Code CLI를 설치했다면 터미널 한 줄로 서버를 삭제할 수 있습니다.

현재 등록된 서버 목록 확인

claude mcp list

출력 예시:

kordoc       npx -y kordoc setup
hwp-mcp      npx -y hwp-mcp
my-test-mcp  /usr/local/bin/my-test-mcp

특정 서버 삭제

claude mcp remove <서버이름>

예를 들어 my-test-mcp를 제거하려면 다음과 같이 입력합니다.

claude mcp remove my-test-mcp

성공 시 "my-test-mcp" 서버가 제거되었습니다. 메시지가 출력됩니다. 이후 claude mcp list로 목록에서 사라졌는지 확인하세요.

주의: 이 명령은 Claude Code CLI 전역 설정(~/.claude/settings.json)에서만 서버를 제거합니다. Claude Desktop을 별도로 사용 중이라면 아래 방법 2도 함께 적용해야 합니다.

방법 2 — claude_desktop_config.json 직접 편집 (Claude Desktop)

GUI 앱인 Claude Desktop은 JSON 설정 파일로 MCP 서버를 관리합니다.

설정 파일 위치

macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS에서 빠르게 파일을 열려면 터미널에서 다음 명령을 실행하세요.

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

특정 서버 한 개 삭제

파일을 텍스트 편집기로 열면 아래와 같은 구조를 볼 수 있습니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    },
    "my-test-mcp": {
      "command": "/usr/local/bin/my-test-mcp",
      "args": []
    }
  }
}

my-test-mcp 블록 전체를 삭제하면 됩니다. 삭제 후 파일은 다음과 같아야 합니다.

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

마지막 항목 뒤에 쉼표가 남지 않도록 주의하세요. JSON에서 trailing comma는 오류입니다.

전체 초기화 (모든 서버 제거)

MCP 서버를 모두 제거하고 완전히 빈 상태로 되돌리려면 mcpServers 값을 빈 객체로 교체합니다.

{
  "mcpServers": {}
}

파일을 저장한 뒤 Claude Desktop을 완전 종료 후 재시작해야 변경 사항이 적용됩니다.

변경 확인 방법

[Claude Desktop]
재시작 → 설정(톱니바퀴) → Extensions 탭 → 서버 목록에서 삭제 확인

[Claude Code CLI]
claude mcp list → 해당 서버 이름이 없으면 성공

Claude Desktop에서 이전에 오류를 일으키던 팝업이 사라지면 정상적으로 제거된 것입니다.

흔한 오류와 해결책

”Command not found: claude”

Claude Code CLI가 설치되지 않은 환경입니다. 방법 2(JSON 직접 편집)를 사용하거나, 다음 명령으로 CLI를 먼저 설치하세요.

npm install -g @anthropic-ai/claude-code

삭제했는데 서버가 여전히 나타남

Claude Desktop이 백그라운드에 남아 있는 경우입니다.

  • macOS: 독(Dock) 아이콘 우클릭 → ‘종료’ 또는 터미널에서 killall Claude
  • Windows: 시스템 트레이 아이콘 우클릭 → ‘종료’

완전히 종료한 뒤 다시 실행하세요.

JSON 저장 후 Claude Desktop이 실행되지 않음

claude_desktop_config.json에 JSON 문법 오류(쉼표 위치, 따옴표 누락 등)가 있을 가능성이 높습니다. 다음 명령으로 문법을 검사하세요.

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

오류 위치가 표시되면 해당 줄을 수정하고 다시 저장합니다.

claude mcp remove 후에도 CLI 오류 지속

CLI는 ~/.claude/settings.json을 봅니다. 직접 열어 해당 서버 항목이 남아 있는지 확인하세요.

cat ~/.claude/settings.json

mcpServers 아래 잔여 항목이 있으면 수동으로 삭제 후 저장합니다.

자주 묻는 질문

claude mcp remove 명령이 없다고 나오면 어떻게 하나요?

Claude CLI(claude 명령)가 설치돼 있지 않거나 버전이 낮을 수 있습니다. npm install -g @anthropic-ai/claude-code로 최신 버전을 설치한 뒤 다시 시도하세요. CLI가 없는 Claude Desktop 단독 사용자는 위에서 설명한 JSON 파일 직접 편집 방법을 사용하면 됩니다.

claude_desktop_config.json 파일이 어디에 있나요?

macOS는 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows는 %APPDATA%\Claude\claude_desktop_config.json 경로에 있습니다. 파일이 없다면 MCP 서버를 한 번도 등록하지 않은 상태이므로 별도 조치가 필요 없습니다.

설정 파일을 수정한 뒤 MCP 서버가 여전히 보이면 어떻게 하나요?

Claude Desktop을 완전히 종료(시스템 트레이 포함)한 뒤 다시 실행해야 변경 사항이 적용됩니다. macOS에서는 Cmd+Q, Windows에서는 트레이 아이콘 우클릭 후 ‘종료’를 선택하세요.

모든 MCP 서버를 한 번에 초기화하려면 어떻게 하나요?

claude_desktop_config.json을 열어 mcpServers 객체 안의 내용을 전부 지우고 빈 객체로 저장한 뒤 Claude Desktop을 재시작하면 됩니다. 위 ‘전체 초기화’ 섹션의 코드 예시를 참고하세요.

MCP 서버 삭제 후 Claude가 오류 없이 시작되는지 어떻게 확인하나요?

Claude Desktop 재시작 후 화면 하단의 MCP 연결 표시등(초록 점)이 보이지 않거나, 설정 패널에서 삭제한 서버 이름이 사라졌다면 정상적으로 제거된 것입니다. Claude Code CLI 사용자는 claude mcp list 명령으로 등록 목록을 확인할 수 있습니다.

MCP 서버를 삭제하면 해당 서버가 했던 작업 기록도 지워지나요?

아니요. 설정에서 제거해도 Claude의 대화 기록이나 서버 자체(로컬 파일·npm 패키지)는 삭제되지 않습니다. 서버와의 연결만 끊기며, 필요하면 나중에 다시 등록할 수 있습니다.

다음 단계

MCP 서버를 깔끔하게 정리한 뒤, 실제로 활용할 만한 한국형 서버를 새로 등록해 보세요. 개발 도구 카테고리에서 검증된 서버들을 확인할 수 있습니다.

한국 문서 처리가 필요하다면 다음 서버들을 참고하세요.

  • 코르독(KorDoc) — HWP·PDF·DOCX 등을 Markdown으로 변환. npx -y kordoc setup으로 설치.
  • HWP-MCP — 한글(.hwp/.hwpx) 문서 읽기·편집. npx -y hwp-mcp으로 설치.
  • 한포지(HwpForge) — HWPX 문서 읽기·쓰기·변환. npx -y @hwpforge/mcp으로 설치.

등록하고 싶은 MCP 서버가 아직 MCP모아에 없다면 서버 제출 페이지에서 추가 요청을 남겨 주세요. 전체 서버 목록은 /servers 에서 확인할 수 있습니다.

이 글과 관련된 MCP 서버