Claude MCP 서버 목록 확인 방법 — claude mcp list·망치 아이콘 활용

MCP 서버를 설치했는데 Claude에서 제대로 인식하는지 확인하고 싶으신가요? claude mcp list 명령어와 Claude Desktop 망치 아이콘 두 가지 방법으로 30초 안에 확인할 수 있습니다. 이 가이드는 설치 확인부터 연결 오류 진단, 정상 동작 테스트까지 한 번에 해결합니다.

---

MCP 서버 목록 확인이 왜 필요한가요?

MCP(Model Context Protocol) 서버는 Claude가 외부 도구·API에 접근하도록 이어주는 브릿지입니다. 설치 명령어를 실행했다고 해서 Claude가 자동으로 인식하는 건 아닙니다. 설정 파일에 올바르게 등록되어야 하고, 프로세스가 실제로 실행되어야 하며, Claude 클라이언트가 이를 로드해야 비로소 쓸 수 있습니다.

목록 확인 없이 “왜 도구가 없지?”라고 헤매는 시간을 줄이기 위해, Claude는 두 가지 확인 경로를 제공합니다.

확인 방법	대상 환경	특징
claude mcp list 명령어	Claude Code CLI	터미널에서 등록 목록 텍스트 출력
망치(🔨) 아이콘	Claude Desktop 앱	GUI로 실시간 연결 서버·도구 확인

---

준비물

• Node.js 18 이상 (npx 포함)
• Claude Code CLI 또는 Claude Desktop 앱 설치 완료
• MCP 서버 최소 1개 등록 시도 완료

---

단계별 확인 방법

1단계: claude mcp list로 등록 서버 확인 (Claude Code CLI)

터미널(Terminal, iTerm2, Windows Terminal 등)을 열고 아래 명령어를 실행합니다.

claude mcp list

정상적으로 서버가 등록돼 있으면 아래와 같이 출력됩니다.

kordoc: npx -y kordoc setup
hwp-mcp: npx -y hwp-mcp
hwpforge: npx -y @hwpforge/mcp

각 줄은 서버이름: 실행 명령어 형식입니다. 아무것도 출력되지 않으면 등록된 서버가 없다는 의미이므로, 먼저 서버를 등록해야 합니다.

특정 서버의 세부 정보를 보려면 아래를 사용합니다.

claude mcp get 서버이름

서버를 새로 추가할 때는 아래 형식으로 등록합니다.

claude mcp add 서버이름 -- npx -y 패키지명

---

2단계: Claude Desktop 망치 아이콘으로 연결 상태 확인

Claude Desktop 앱을 실행하면 채팅 입력창 하단에 망치 아이콘이 나타납니다. 이 아이콘을 클릭하면 현재 활성화된 MCP 서버 목록과 각 서버가 제공하는 도구 이름이 팝업으로 표시됩니다.

[채팅 입력창]
  ──────────────────────────
  [📎 첨부] [🔨 MCP 도구]  [전송]
  ──────────────────────────
        ↓ 클릭
  ┌─────────────────────────┐
  │ 연결된 MCP 서버          │
  │ • kordoc (3개 도구)      │
  │ • hwp-mcp (5개 도구)    │
  │ • hwpforge (4개 도구)   │
  └─────────────────────────┘

망치 아이콘이 보이지 않는다면 아직 연결된 서버가 없거나 설정 파일을 아직 읽지 못한 상태입니다. 다음 단계로 설정 파일을 점검합니다.

---

3단계: claude_desktop_config.json 구성 점검

Claude Desktop은 아래 경로의 JSON 파일로 MCP 서버를 관리합니다.

운영체제	설정 파일 경로
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

파일을 열어 mcpServers 항목이 올바른지 확인합니다. 예시입니다.

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

주요 점검 포인트:

• JSON 문법 오류 없이 쌍따옴표, 중괄호, 쉼표가 맞는지 확인
• command와 args 배열이 실제로 실행 가능한 명령어인지 확인
• 파일을 수정한 뒤에는 Claude Desktop 앱을 완전히 종료하고 재시작해야 반영됩니다

---

4단계: MCP 서버 연결 오류 진단

목록에 서버가 보이지 않거나 망치 아이콘에서 비활성 상태로 표시될 때 순서대로 점검합니다.

오류 진단 흐름:

서버가 목록에 없음
    │
    ▼
claude_desktop_config.json에 항목이 있는가?
    │ 없음 → 항목 추가 후 재시작
    │ 있음 ↓
JSON 문법 오류가 있는가?
    │ 있음 → 수정 후 재시작
    │ 없음 ↓
npx / node 명령어가 PATH에 있는가?
    │ 없음 → Node.js 설치 또는 절대 경로 사용
    │ 있음 ↓
서버 패키지가 정상 설치됐는가?
    │ → 수동으로 npx -y 패키지명 실행해 오류 확인

Claude Desktop의 오류 로그는 macOS 기준 아래 경로에서 확인할 수 있습니다.

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

---

5단계: 정상 연결 테스트

설정이 올바르게 됐다면 Claude 채팅창에서 직접 테스트합니다. 예를 들어 코르독(KorDoc)이 연결된 경우 아래처럼 요청합니다.

사용자: HWP 파일을 Markdown으로 변환해줘.
Claude: (kordoc 도구를 호출해 변환 결과 반환)

도구 호출이 실패하면 Claude가 “도구를 사용할 수 없습니다”라는 메시지를 반환합니다. 이 경우 3단계, 4단계를 반복 점검합니다.

---

관련 MCP 서버

목록 확인 연습에 활용하기 좋은 한국산 MCP 서버를 소개합니다. 모두 API 키 없이 바로 설치할 수 있습니다.

서버	설명	설치 명령어
코르독(KorDoc)	HWP·PDF·DOCX 등 공문서를 Markdown으로 변환	npx -y kordoc setup
HWP-MCP	한글(.hwp/.hwpx) 문서 읽기·편집·생성	npx -y hwp-mcp
한포지(HwpForge)	HWPX 문서를 AI 에이전트가 읽고 쓰고 변환	npx -y @hwpforge/mcp

더 많은 MCP 서버는 개발도구 카테고리와 전체 서버 목록에서 찾아볼 수 있습니다.

---

자주 묻는 질문

claude mcp list 명령어가 없다고 나옵니다. 어떻게 해야 하나요?

Claude Code CLI가 설치되지 않았거나 버전이 낮을 수 있습니다. 아래 명령어로 최신 버전을 설치한 뒤 다시 시도하세요.

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

망치 아이콘이 보이지 않습니다. MCP 서버가 연결되지 않은 건가요?

망치 아이콘은 claude_desktop_config.json에 최소 1개 이상의 MCP 서버가 등록되어 있고 Claude Desktop을 재시작했을 때 나타납니다. 설정 파일 경로와 JSON 문법을 다시 확인하세요.

목록에는 보이는데 도구가 실행되지 않습니다. 왜 그런가요?

서버 프로세스가 실제로 실행 중이지 않거나 Node.js, npx 경로가 잘못됐을 수 있습니다. claude mcp list 결과에서 해당 서버의 command 값과 설치 환경을 맞춰주세요. 로그 파일도 함께 확인하면 원인을 빠르게 파악할 수 있습니다.

여러 MCP 서버를 등록하면 충돌이 생기나요?

일반적으로 각 MCP 서버는 독립된 프로세스로 동작하므로 서로 충돌하지 않습니다. 단, 동일한 포트를 쓰도록 잘못 설정된 커스텀 서버끼리는 충돌할 수 있으니 포트 설정을 개별 확인하세요.

Claude Code와 Claude Desktop의 MCP 서버 목록이 다를 수 있나요?

네, 다를 수 있습니다. Claude Code CLI는 ~/.claude.json 또는 프로젝트 설정을 참조하고, Claude Desktop은 claude_desktop_config.json을 별도로 읽습니다. 두 환경에 모두 등록하려면 각각 설정해야 합니다.

MCP 서버를 삭제하려면 어떻게 하나요?

Claude Code에서는 아래 명령어로 등록을 해제할 수 있습니다.

claude mcp remove 서버이름

Claude Desktop은 claude_desktop_config.json의 mcpServers에서 해당 항목을 삭제하고 앱을 재시작하세요.

---

다음 단계

MCP 서버 목록 확인과 연결 점검이 완료됐다면, 이제 실제로 유용한 서버를 추가해볼 차례입니다. 전체 가이드 목록에서 각 서버의 설치·설정 방법을 확인하거나, MCP모아 서버 디렉토리에서 한국산 MCP 서버를 탐색해보세요. 직접 만든 MCP 서버가 있다면 서버 등록도 환영합니다.