Desktop Commander MCP

AI로 파일 검색, 업데이트, 관리 및 터미널 명령 실행

코드와 텍스트 작업, 프로세스 실행, 작업 자동화를 통해 다른 AI 편집기를 뛰어넘어 보세요 - API 토큰 비용 대신 호스트 클라이언트 구독을 사용할 수 있습니다.

🖥️ Desktop Commander 앱 사용해 보기 (베타)

더 나은 환경을 원하세요? Desktop Commander App은 MCP 서버가 제공하는 모든 기능을 제공하며, 추가로:

• 모든 AI 모델 사용 — Claude, GPT-4.5, Gemini 2.5 또는 원하는 모델을 모두 사용할 수 있습니다

• 파일 변경 실시간 확인 — AI가 파일을 편집하는 동안 시각적 파일 미리보기 제공

• 사용자 정의 MCP 및 컨텍스트 추가 — 구성 파일 없이 자체 도구로 확장

• 출시 예정 — 스킬 시스템, 받아쓰기, 예약된 백그라운드 작업 등

👉 앱 다운로드 (macOS 및 Windows)

아래의 MCP 서버는 Claude Desktop 및 다른 MCP 클라이언트에서 여전히 완벽하게 작동합니다 — 앱은 전용의 완성된 환경을 원하는 사용자를 위한 것입니다.

Related MCP server: TermPipe MCP

목차

• 기능

• 설치 방법

• 시작하기

• 사용법

• 파일 미리보기 UI 및 마크다운 편집기

• 장기 실행 명령 처리

• 진행 중인 작업 및 TODO

• 스폰서 및 후원자

• 웹사이트

• 미디어

• 사용 후기

• 자주 묻는 질문

• 기여하기

• 라이선스

모든 AI 개발 도구를 한곳에 모았습니다. Desktop Commander는 모든 개발 도구를 하나의 채팅에 통합합니다. Model Context Protocol (MCP)을 통해 컴퓨터에서 장기 실행 터미널 명령을 실행하고 프로세스를 관리하세요. MCP Filesystem Server를 기반으로 하여 추가 검색 및 치환 파일 편집 기능을 제공합니다.

기능

• 원격 AI 제어 - ChatGPT, Claude 웹 및 기타 AI 서비스에서 Remote MCP를 통해 Desktop Commander 사용

• 파일 미리보기 UI - 렌더링된 마크다운, 인라인 이미지, 확장 가능 콘텐츠, 내장 마크다운 편집기 및 빠른 "폴더에서 열기" 접근이 포함된 Claude Desktop의 시각적 파일 미리보기

• 향상된 터미널 명령 - 대화형 프로세스 제어 기능

• 메모리에서 코드 실행 - 파일을 저장하지 않고 Python, Node.js, R 실행

• 즉시 데이터 분석 - CSV/JSON/Excel 파일 분석을 요청하기만 하면 됩니다

• 기본 Excel 파일 지원 - 외부 도구 없이 Excel 파일(.xlsx, .xls, .xlsm) 읽기, 쓰기, 편집, 검색

• PDF 지원 - 텍스트 추출로 PDF 읽기, 마크다운에서 새 PDF 생성, 기존 PDF 수정

• DOCX 지원 - 정밀한 XML 편집 및 마크다운에서 DOCX 변환을 통해 Word 문서(.docx) 읽기, 쓰기, 편집, 검색

• 실행 중인 프로세스와 상호 작용 (SSH, 데이터베이스, 개발 서버)

• 출력 스트리밍으로 터미널 명령 실행

• 명령 타임아웃 및 백그라운드 실행 지원

• 프로세스 관리 (프로세스 목록 및 종료)

• 장기 실행 명령을 위한 세션 관리

• 프로세스 출력 페이지네이션 - 컨텍스트 오버플로를 방지하기 위해 오프셋/길이 제어로 터미널 출력 읽기

• 서버 구성 관리:

  • 구성 값 가져오기/설정

  • 여러 설정을 한 번에 업데이트

  • 서버 재시작 없이 동적 구성 변경

• 전체 파일 시스템 작업:

  • 파일 읽기/쓰기 (텍스트, Excel, PDF, DOCX)

  • 디렉토리 생성/목록 표시

  • 재귀 디렉토리 목록 - 큰 폴더에 대한 구성 가능한 깊이 및 컨텍스트 오버플로 보호 제공

  • 파일/디렉토리 이동

  • 파일 및 콘텐츠 검색 (Excel 콘텐츠 포함)

  • 파일 메타데이터 가져오기

  • 음수 오프셋 파일 읽기: Unix tail과 유사하게 파일 끝에서 음수 오프셋 값으로 파일 읽기

• 코드 편집 기능:

  • 작은 변경을 위한 정밀 텍스트 치환

  • 큰 변경을 위한 전체 파일 재작성

  • 여러 파일 지원

  • 패턴 기반 치환

  • vscode-ripgrep 기반 폴더 내 재귀 코드/텍스트 검색

• 포괄적인 감사 로깅:

  • 모든 도구 호출 자동 기록

  • 10MB 크기 제한의 로그 순환

  • 상세 타임스탬프 및 인자 기록

• 안전 가드레일 (샌드박스가 아닙니다 — SECURITY.md 참조):

  • 파일 작업 시 심볼릭 링크 추적 방지

  • 실수로 실행되지 않도록 명령 차단 목록 적용

  • 완전한 격리를 위한 Docker 격리 제공

설치 방법

Claude Desktop에 설치

Desktop Commander는 Claude Desktop용 다양한 설치 방법을 제공합니다.

📋 업데이트 및 제거 정보: 옵션 1, 2, 3, 4, 6은 자동 업데이트입니다. 옵션 5는 수동 업데이트가 필요합니다. 자세한 내용은 아래를 참조하세요.

터미널에서 다음 명령을 실행하세요:

npx @wonderwhy-er/desktop-commander@latest setup

디버깅 모드 (Node.js 인스펙터 연결 허용):

npx @wonderwhy-er/desktop-commander@latest setup --debug

설치 중 명령줄 옵션:

• --debug: Node.js 인스펙터용 디버깅 모드 활성화

• --no-onboarding: 신규 사용자 온보딩 프롬프트 비활성화

Claude가 실행 중이면 먼저 종료하세요.

✅ 자동 업데이트: 예 — Claude를 재시작할 때 자동 업데이트
🔄 수동 업데이트: 설정 명령을 다시 실행
🗑️ 제거: npx @wonderwhy-er/desktop-commander@latest remove 실행

curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash

이 스크립트는 모든 종속성과 구성을 자동으로 처리합니다.

✅ 자동 업데이트: 예
🔄 수동 업데이트: 위의 bash 설치 명령을 다시 실행
🗑️ 제거: npx @wonderwhy-er/desktop-commander@latest remove 실행

1. 방문: https://smithery.ai/server/@wonderwhy-er/desktop-commander

2. Smithery에 로그인 아직 로그인하지 않았다면

3. 클라이언트 선택: 오른쪽에서 (Claude Desktop) 선택

4. 제공된 키로 설치: 클라이언트 선택 후 나타나는 키를 사용하여 설치

5. Claude Desktop 재시작

✅ 자동 업데이트: 예 - Claude를 재시작할 때 자동 업데이트
🔄 수동 업데이트: Smithery 페이지를 방문하여 다시 설치

claude_desktop_config.json에 다음 항목을 추가하세요:

• Mac에서: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows에서: %APPDATA%\Claude\claude_desktop_config.json

• Linux에서: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest"
      ]
    }
  }
}

Claude가 실행 중이면 종료하세요.

✅ 자동 업데이트: 예 — Claude를 재시작할 때 자동 업데이트
🔄 수동 업데이트: 설정 명령을 다시 실행
🗑️ 제거: npx @wonderwhy-er/desktop-commander@latest remove 실행하거나 claude_desktop_config.json에서 항목을 제거하세요.

git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
cd DesktopCommanderMCP
npm run setup

Claude가 실행 중이면 종료 후 시작하세요.

설정 명령이 모든 종속성을 설치, 서버를 빌드하고 Claude 데스크톱 앱을 구성합니다.

❌ 자동 업데이트: 아니요 — 수동 git 업데이트 필요
🔄 수동 업데이트: cd DesktopCommanderMCP && git pull && npm run setup
🗑️ 제거: npx @wonderwhy-er/desktop-commander@latest remove을 실행하거나, 복제된 디렉토리와 Claude 구성에서 MCP 서버 항목을 제거하세요.

격리된 환경을 원하거나 Node.js가 설치되지 않은 사용자에게 적합합니다. 영구 작업 환경을 갖춘 보안 Docker 컨테이너에서 실행됩니다.

사전 요구 사항: Docker Desktop 설치 및 실행 중 상태, Claude Desktop 앱 설치.

macOS/Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)

Windows PowerShell:

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'))

설치 프로그램이 Docker를 확인하고, 이미지를 가져오고, 폴더 마운트를 요청한 다음 Claude Desktop을 구성합니다.

Docker 지속성: 설치된 도구, 구성, 작업 파일, 패키지 캐시가 재시작 후에도 유지됩니다.

기본 설정 (파일 접근 없음):

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/desktop-commander:latest"]
    }
  }
}

폴더 마운트 포함:

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/username/Desktop:/mnt/desktop",
        "-v", "/Users/username/Documents:/mnt/documents",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}

고급 폴더 마운트:

{
  "mcpServers": {
    "desktop-commander-in-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "dc-system:/usr",
        "-v", "dc-home:/root", 
        "-v", "dc-workspace:/workspace",
        "-v", "dc-packages:/var",
        "-v", "/Users/username/Projects:/mnt/Projects",
        "-v", "/Users/username/Downloads:/mnt/Downloads",
        "mcp/desktop-commander:latest"
      ]
    }
  }
}

macOS/Linux:

# Check status
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --status

# Reset all persistent data
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset

Windows PowerShell:

# Check status
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Status

# Reset all data
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Reset

# Show help
$script = (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'); & ([ScriptBlock]::Create("$script")) -Help

문제 해결: 초기화 후 재설치:

bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset && bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)

✅ 자동 업데이트: 예 — latest 태그가 자동으로 최신 버전으로 가져와짐
🔄 수동 업데이트: docker pull mcp/desktop-commander:latest 실행 후 Claude 재시작

다른 클라이언트에 설치

Desktop Commander는 MCP 호환 클라이언트와 함께 사용할 수 있습니다. 표준 JSON 구성은 다음과 같습니다:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
    }
  }
}

아래 위치의 클라이언트 MCP 구성 파일에 이 항목을 추가하세요:

View MCP Server in Directory

또는 ~/.cursor/mcp.json (전역) 또는 프로젝트 폴더의 .cursor/mcp.json (프로젝트별)에 수동으로 추가하세요.

자세한 내용은 Cursor MCP 문서를 참조하세요.

~/.codeium/windsurf/mcp_config.json에 추가하세요. 자세한 내용은 Windsurf MCP 문서를 참조하세요.

프로젝트의 .vscode/mcp.json 또는 VS Code 사용자 설정(JSON)에 추가하세요. Chat > MCP 아래에서 MCP가 활성화되어 있는지 확인하세요. Agent 모드에서 작동합니다.

자세한 내용은 VS Code MCP 문서를 참조하세요.

VS Code의 Cline 확장 설정에서 구성하세요. Cline 사이드바를 열고 MCP 서버 아이콘을 클릭한 후 위의 JSON 구성을 추가하세요. 자세한 내용은 Cline MCP 문서를 참조하세요.

Roo Code MCP 구성 파일에 추가하세요. 자세한 내용은 Roo Code MCP 문서를 참조하세요.

claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

현재 프로젝트에만 설치하려면 --scope user를 제거하세요. 자세한 내용은 Claude Code MCP 문서를 참조하세요.

"수동 추가" 기능을 사용하고 위의 JSON 구성을 붙여넣으세요. 자세한 내용은 Trae MCP 문서를 참조하세요.

Kiro > MCP Servers로 이동하여 + Add를 클릭하고 위의 JSON 구성을 붙여넣으세요. 자세한 내용은 Kiro MCP 문서를 참조하세요.

Codex는 TOML 구성을 사용합니다. 다음 명령을 실행하여 Desktop Commander를 추가하세요:

codex mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

또는 ~/.codex/config.toml에 수동으로 추가하세요:

[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander@latest"]

자세한 내용은 Codex MCP 문서를 참조하세요.

JetBrains IDE에서 **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**로 이동하여 + Add를 클릭하고 As JSON을 선택한 후 위의 JSON 구성을 붙여넣으세요. 자세한 내용은 JetBrains MCP 문서를 참조하세요.

~/.gemini/settings.json에 추가하세요:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
    }
  }
}

자세한 내용은 Gemini CLI 문서를 참조하세요.

Cmd/Ctrl+Shift+P를 누르고 Augment 패널을 열어 desktop-commander라는 새 MCP 서버를 위의 JSON 구성으로 추가하세요. 자세한 내용은 Augment Code MCP 문서를 참조하세요.

다음 명령을 실행하여 Desktop Commander를 추가하세요:

qwen mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest

또는 .qwen/settings.json(프로젝트) 또는 ~/.qwen/settings.json(전역)에 추가하세요. 자세한 내용은 Qwen Code MCP 문서를 참조하세요.

ChatGPT, Claude 웹 및 기타 AI 서비스에서 Remote MCP를 통해 Desktop Commander를 사용하세요 — 데스크톱 앱이 필요 없습니다.

👉 mcp.desktopcommander.app에서 시작하기

작동 방식:

1. 컴퓨터에서 가벼운 Remote Device를 실행합니다

2. 클라우드 Remote MCP 서비스에 안전하게 연결됩니다

3. AI가 클라우드를 통해 기기로 명령을 전송합니다

4. 명령이 로컬에서 실행되고 결과가 AI로 반환됩니다

5. 통제권은 사용자에게 있습니다 — Ctrl+C로 언제든 중지할 수 있습니다

보안

• ✅ 기기는 사용자가 시작할 때만 실행됩니다

• ✅ 명령은 사용자 권한으로 실행됩니다

• ✅ 안전한 OAuth 인증 및 암호화된 통신 채널

Desktop Commander 업데이트 및 제거

자동 업데이트 (옵션 1, 2, 3, 4 및 6)

옵션 1(npx), 옵션 2(bash 설치 프로그램), 3(Smithery), 4(수동 구성) 및 6(Docker) 은 Claude를 다시 시작할 때마다 자동으로 최신 버전으로 업데이트됩니다. 수동 조작이 필요 없습니다.

수동 업데이트 (옵션 5)

• 옵션 5(로컬 체크아웃): cd DesktopCommanderMCP && git pull && npm run setup

Desktop Commander 제거

🤖 자동 제거 (권장)

Desktop Commander를 완전히 제거하는 가장 쉬운 방법:

npx @wonderwhy-er/desktop-commander@latest remove

이 자동 제거 프로그램은 다음을 수행합니다:

• ✅ Claude의 MCP 서버 구성에서 Desktop Commander를 제거합니다

• ✅ 변경 전에 Claude 구성의 백업을 생성합니다

• ✅ 완전한 패키지 제거를 위한 안내를 제공합니다

• ✅ 문제 발생 시 백업에서 복원합니다

🔧 수동 제거

자동 제거 프로그램이 작동하지 않거나 수동 제거를 선호하는 경우:

Claude 구성에서 제거

1. Claude Desktop 구성 파일을 찾습니다:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

2. 구성 파일을 편집합니다:

• 텍스트 편집기에서 파일을 엽니다

• "mcpServers" 섹션에서 "desktop-commander" 항목을 찾아 제거합니다

• 파일을 저장합니다

예시 - 이 섹션을 제거하세요:

{
    "desktop-commander": {
      "command": "npx",
      "args": ["@wonderwhy-er/desktop-commander@latest"]
    }
}

Claude Desktop을 닫고 다시 시작하여 제거를 완료합니다.

🆘 문제 해결

자동 제거가 실패하는 경우:

• 수동 제거를 대체 방법으로 사용하세요

제거 후 Claude가 시작되지 않는 경우:

• 제거 프로그램이 생성한 백업 구성 파일을 복원하세요

• 또는 claude_desktop_config.json의 JSON 구문을 수동으로 수정하세요

도움이 필요하신가요?

• Discord 커뮤니티에 가입하세요: https://discord.com/invite/kQ27sNnZr7

시작하기

Desktop Commander가 설치되고 Claude Desktop이 다시 시작되면 Claude 경험을 한층 더 강화할 준비가 된 것입니다!

🚀 신규 사용자 온보딩

Desktop Commander에는 가능한 기능을 발견하는 데 도움이 되는 지능형 온보딩이 포함되어 있습니다:

신규 사용자: 이제 막 시작한 경우(성공적인 명령 10개 미만), Desktop Commander를 성공적으로 사용한 후 Claude가 유용한 시작 가이드와 실용적인 튜토리얼을 자동으로 제공합니다.

언제든지 도움 요청: 다음 문구를 말하면 언제든지 온보딩 지원을 요청할 수 있습니다:

• "Desktop Commander 시작하는 방법을 도와줘"

• "Desktop Commander 예시를 보여줘"

• "Desktop Commander로 무엇을 할 수 있어?"

그러면 Claude가 초보자 친화적인 튜토리얼과 예시를 보여줍니다:

• 📁 Downloads 폴더 자동 정리

• 📊 Python으로 CSV/Excel 파일 분석

• ⚙️ GitHub Actions CI/CD 설정

• 🔍 코드베이스 탐색 및 이해

• 🤖 대화형 개발 환경 실행

사용법

서버는 여러 범주로 구성된 포괄적인 도구 세트를 제공합니다:

사용 가능한 도구

빠른 예시

데이터 분석:

"Analyze sales.csv and show top customers" → Claude runs Python code in memory

원격 접속:

"SSH to my server and check disk space" → Claude maintains SSH session

개발:

"Start Node.js and test this API" → Claude runs interactive Node session

도구 사용 예시

검색/바꾸기 블록 형식:

filepath.ext
<<<<<<< SEARCH
content to find
=======
new content
>>>>>>> REPLACE

예시:

src/main.js
<<<<<<< SEARCH
console.log("old message");
=======
console.log("new message");
>>>>>>> REPLACE

향상된 편집 블록 기능

edit_block 도구는 안정성을 높이기 위해 여러 가지 개선 사항이 포함되어 있습니다:

1. 프롬프트 개선: 도구 설명은 이제 한 번의 큰 변경 대신 여러 개의 작고 집중된 편집을 수행하도록 강조합니다

2. 퍼지 검색 대체: 정확히 일치하는 항목을 찾지 못하면 퍼지 검색을 수행하고 상세한 피드백을 제공합니다

3. 문자 단위 차이: {-제거됨-}{+추가됨+} 형식으로 정확히 무엇이 다른지 보여줍니다

4. 다중 항목 지원: expected_replacements 매개변수로 여러 항목을 한 번에 바꿀 수 있습니다

5. 포괄적인 로깅: 모든 퍼지 검색은 분석 및 디버깅을 위해 기록됩니다

검색이 실패하면 유사도 백분율, 실행 시간, 문자 차이를 포함하여 가장 가깝게 일치한 항목에 대한 자세한 정보를 볼 수 있습니다. 이러한 세부 정보는 모두 나중에 퍼지 검색 로그 도구를 사용하여 분석할 수 있도록 자동으로 기록됩니다.

Docker 지원

🐳 격리된 환경 사용

Desktop Commander는 Docker 컨테이너에서 실행되어 호스트 시스템으로부터 완전히 격리되므로 컴퓨터에 대한 위험이 전혀 없습니다. 이는 테스트, 개발 또는 완전한 샌드박싱을 원할 때 이상적입니다.

설치 안내

1. Windows/Mac용 Docker 설치

   • docker.com에서 Docker Desktop을 다운로드하고 설치하세요

2. Desktop Commander Docker 설정 가져오기

   • 방문: https://hub.docker.com/mcp/server/desktop-commander/manual

   • 옵션 A: 제공된 터미널 명령을 사용하여 자동 설정을 수행하세요

   • 옵션 B: "Standalone"을 클릭하여 config JSON을 가져온 다음 Claude Desktop 설정에 수동으로 추가하세요

3. 머신 폴더 마운트 (준비 중)

   • 로컬 디렉터리를 Docker 컨테이너에 마운트하는 방법에 대한 지침이 곧 제공될 예정입니다

   • 이렇게 하면 완전한 격리를 유지하면서 파일 작업을 할 수 있습니다

Docker 사용의 이점

• 호스트 시스템으로부터 완전한 격리

• 여러 머신 환경에서도 일관된 환경

• 쉬운 정리 — 작업이 끝나면 컨테이너를 제거하기만 하면 됩니다

• 새 기능 또는 설정을 테스트하기에 완벽

URL 지원

• read_file은 이제 로컬 파일과 URL 모두에서 콘텐츠를 가져올 수 있습니다

• 예: read_file에 isUrl: true 매개변수를 사용하면 웹 리소스에서 읽을 수 있습니다

• 원격 소스의 텍스트 및 이미지 콘텐츠를 모두 처리합니다

• 이미지(로컬 또는 URL)는 텍스트가 아닌 Claude 인터페이스에서 시각적으로 표시됩니다

• Claude는 실제 이미지 콘텐츠를 보고 분석할 수 있습니다

• URL 요청에는 기본 30초의 타임아웃이 적용됩니다

파일 미리보기 UI 및 Markdown 편집기

Desktop Commander에는 AI가 파일을 작업할 때 시각적으로 렌더링하는 풍부한 파일 미리보기 위젯을 Claude Desktop에 포함합니다.

지원되는 파일 형식

• Markdown — 내장 편집기를 갖춘 렌더링된 미리보기

• 이미지 — 인라인 표시(PNG, JPEG, GIF, WebP 등)

• 코드 파일 — 구문 강조된 소스 보기

• HTML — 소스 보기와 전환 가능한 렌더링된 미리보기

• 디렉터리 — 확장/축소 및 지연 로딩이 가능한 인터랙티브 트리

• PDF, Excel, DOCX — 기본 콘텐츠 추출 및 표시

Markdown 편집기

Claude Desktop에서 .md 파일을 볼 때 별도의 앱을 열 필요 없이 미리보기 패널 안에서 직접 편집할 수 있습니다.

사용 방법:

1. Claude에게 마크다운 파일을 읽거나 생성하도록 요청하세요

2. ⤢ Expand 버튼을 사용하여 파일 미리보기를 전체 화면으로 확장하세요

3. 전체 화면 모드에서 편집기가 자동으로 활성화됩니다

4. 실시간 미리보기 전환, 복사, 실행 취소 및 저장 컨트롤을 사용해 콘텐츠를 편집하세요

5. 변경사항은 디스크에 저장됩니다; 접으면 인라인 보기로 돌아갑니다

편집기 기능:

• 실시간 편집/미리보기 전환 — 원시 markdown과 렌더링 출력 사이를 전환

• 디스크에 자동 저장 및 저장 상태 표시기

• 저장되지 않은 변경을 원래대기 위한 실행 취소 지원

• 전체 markdown 소스를 가져올 수 있는 복사 버튼

• 편집기에서 열기 — 패널에서 바로 기본 markdown 앱을 실행

• 부분 파일 인식 — 파일이 부분적으로만 읽혀도 주변 줄을 로드하거나 병합

• 텍스트 선택 컨텍스트 — 미리보기 모드에서 텍스트를 선택하면 AI가 해당 선택을 참조 가능

디렉터리 브라우저

Claude가 list_directory를 실행하면 워크패널 안에서 인터랙티브 파일 트리로 결과가 표시됩니다 — 단순히 원시 텍스트 출력이 아닙니다.

기능:

• 확장 가능한 트리 — 클릭하면 폴더가 확장/축고, 최상위 콘텐츠는 즉시 표시됩니다

• 지연 로딩 — 초기 보기를 빠르게 유지하기 위해 하위 폴더는 요청 시 로드됩니다

• 대용량 디렉터리 처리량 — 항목이 많은 디렉터리는 보기를 압도하지 않도록 ⚠ 클릭하여 모두 로드 버튼이 표시됩니다

• Finder/Explorer에서 열기 — 각 폴더에 파일 관리자에서 위치를 보여주는 즉시 열기 버튼이 있습니다

• 클릭으로 미리보기 — 트리에서 파일을 클릭하면 파일 미리보기 패널에 바로 열립니다

• 뒤로 이동 — 트리에서 파일을 연 뒤 ← Back 버튼을 누르면 디렉터리 보기로 돌아갑니다

기타 미리보기 기능

• 확장/축소 — 간결한 요약 행과 전체 패널 사이를 전환

• 폴더에서 열기 — 클릭 한 번으로 Finder/Explorer에서 파일 위치를 표시

• 더 많은 라인 로드 — 부분적으로 읽힌 창의 위나 아래 콘텐츠를 증분적으로 로드

• 텍스트 선택 — 모든 미리보기에서 텍스트를 하이라이트하며, AI는 선택한 텍스트를 보고 참조할 수 있습니다

퍼지 검색 로그 분석 (npm 스크립트)

퍼지 검색 로깅 시스템에는 MCP 환경 외부에서 로그를 분석하기 위한 편리한 npm 스크립트가 포함되어 있습니다:

# View recent fuzzy search logs
npm run logs:view -- --count 20

# Analyze patterns and performance
npm run logs:analyze -- --threshold 0.8

# Export logs to CSV or JSON
npm run logs:export -- --format json --output analysis.json

# Clear all logs (with confirmation)
npm run logs:clear

이 스크립트에 대한 자세한 문서는 scripts/README.md를 참조하세요.

퍼지 검색 로그

Desktop Commander는 edit_block 도구에서 퍼지 검색 작업을 위한 광범위한 로깅을 포함합니다. 정확히 일치하는 항목을 찾지 못하면 시스템은 퍼지 검색을 수행하고 분석을 위한 상세 정보를 로그에 기록합니다.

기록되는 내용

모든 퍼지 검색 작업은 다음을 기록합니다:

• 검색 및 발견된 텍스트: 검색한 텍스트 vs 발견된 텍스트

• 유사도 점수: 일치가 얼마나 가까운지 (0–100%)

• 실행 시간: 검색을 수행하는 데 걸린 시간

• 문자 차이: 정확히 무엇이 다른지를 보여주는 상세 diff

• 파일 메타데이터: 확장자, 검색/발견 텍스트 길이

• 문자 코드: 차이를 초발하는 특정 문자 코드

로그 위치

로그는 자동으로 다음에 저장됩니다:

• macOS/Linux: ~/.claude-server-commander-logs/fuzzy-search.log

• Windows: %USERPROFILE%\.claude-server-commander-logs\fuzzy-search.log

알아볼 수 있는 정보

퍼지 검색 로그는 다음을 이해하는 데 도움이 될 것입니다:

1. 정확한 일치가 실패한다: 공백 차이나 줄바' 끝, 문자 인코딩과 같은 공통 문제

2. 성능 패턴: 검색 복잡성이 실행 시간에 미치는 영향

3. 파일 유형 문제: 파일 확장자에 따라 일치하는 데 취약한 항목이 많음

4. 구조 인코딩 문제: diff 발생시키는 특정 문자 코드

감사 로그

Desktop Commander는 이제 모든 도구 호출에 대한 폭넓은 로깅을 포함합니다:

로그되는 내용

• 모든 도구 호출은 타임스탬프, 도구 이름, 인자(개인정보 보호를 위해 삭제됨)와 함께 로그됩니다

• 로그는 10MB에 도달하면 자동으로 회전합니다

로그 위치

로그는 다음 위치에 저장됩니다:

• macOS/Linux: ~/.claude-server-commander/claude_tool_call.log

• Windows: %USERPROFILE%\.claude-server-commander\claude_tool_call.log

이 감사 기록은 디버깅, 보안 모니터링 및 Claude가 시스템과의 상호 작용을 이해하는 데 도움이 됩니다.

오래 실행되는 명령 처리

시간이 오래 걸리는 명령이 있는 경우:

구성 관리

⚠️ 중요한 보안 경고

포괄적인 보안 정보 및 취약점 신고: SECURITY.md를 참조하세요.

1. 알려진 보안 제한: 디렉터리 제한과 명령 차단은 심볼릭 링크, 명령 대체, 절대 경로, 코드 실행 등 여러 방법으로 우회될 수 있습니다

2. 구성은 항상 실제 작업을 수행중인 별도의 채팅 창에서 변경하세요. Claude가 파일 시스템 접근 제한을 만나면 allowedDirectories 같은 설정을 변경하려 할 수 있습니다.

3. 현재 allowedDirectories 설정은 파일 시스템 작업만 제한하며, 터미널 명령은 제한하지 않습니다. 터미널 명령은 여전히 허용된 디렉터리 외부의 파일에 접근할 수 있습니다.

4. 운영 환경 보안을 위해: 호스트 시스템과 완전히 격리되는 Docker 설치를 사용하세요.

구성 도구

제공된 도구를 사용하여 서버 구성을 관리할 수 있습니다:

// Get the entire config
get_config({})

// Set a specific config value
set_config_value({ "key": "defaultShell", "value": "/bin/zsh" })

// Set multiple config values using separate calls
set_config_value({ "key": "defaultShell", "value": "/bin/bash" })
set_config_value({ "key": "allowedDirectories", "value": ["/Users/username/projects"] })

구성은 서버의 작업 디렉터리의 config.json에 저장되며 서버 재시작 후에도 유지됩니다.

fileWriteLineLimit 이해하기

fileWriteLineLimit 설정은 단일 write_file 작업에서 쓰기 가능한 라인 수를 제어합니다(기본값: 50줄). 이 제한은 몇 가지 중요한 이유가 존재합니다:

제한이 존재하는 이유:

• AA는 토큰을 낭비합니다: 파일에서 작은 편집 두 번을 수행하는 대신 전체를 다시 쓰려고 합니다. 더 작은 변경으로 일하게 하여 시간과 토큰을 절약하려는 것입니다

• Claude UX 메시지 제한: 하나의 메시지 내에 제한이 있으며 "Continue"를 눌러도 실제로 계속되지 않습니다. 여기서 목표는 AI가 여러 완료된 청크가 생성되도록 작게 작업하게 하여 다시 시작할 때 마지막 청크에서부터만 재개하면 됩니다

한도 설정:

// You can set it to thousands if you want
set_config_value({ "key": "fileWriteLineLimit", "value": 1000 })

// Or keep it smaller to force more efficient behavior
set_config_value({ "key": "fileWriteLineLimit", "value": 25 })

최대값: 기술상 제한이 없으니 필요한 경우 수천을 설정할 수 있습니다.

사용 모범 사례:

• 기본값(50)을 유지하여 AI가 효율적으로 동작하고 토큰 불필요 소모를 방지하세요

• 한도 초과 시 시스템에서 분해 하도록 자동으로 제안합니다

• 작은 청크는 Claude가 메시지 한도에 도달해도 실패하는 청크 수가 적다는 것을 의미힙니다

모범 사례

1. 구성 변경 전용 채팅을 묻혀야 합니다: 모든 구성 변경을 한 채팅에서 완료한 후 실제 작업을 새 채팅에서 시작하세요.

2. 빈 allowedDirectories에 주의: 이 설정을 빈 배열([])로 지정하면 모든 파일 시스템에 접근할 수 있습니다.

3. 구체적인 경로 사용: /처럼 넓은 경로 대신 정확히 접근할 디렉터리를 지정하세요.

4. 변경 후 항상 구성 검증: get_config({})를 사용하여 변경 사항이 올바르게 적용되었는지 확인하세요.

명령줄 옵션

Desktop Commander는 동작을 사용자가 지정할 수 있는 여러 명령줄 옵션을 지원합니다.

온보딩 비활성화

Desktop Commander는 기본적으로 신규 사용자(도구 호출 10회 미만)에게 유용한 온보딩 프롬프트를 표시합니다. 다음을 방지할 수 있습니다:

# Disable onboarding for this session
node dist/index.js --no-onboarding

# Or if using npm scripts
npm run start:no-onboarding

# For npx installations, modify your claude_desktop_config.json:
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest",
        "--no-onboarding"
      ]
    }
  }
}

온보딩이 자동으로 비활성화되는 경우:

• MCP 클라이언트 이름이 "desktop-commander"로 설정된 경우

• --no-homebound 플래그를 사용할 때

• 사용자가 온보딩 프롬프트를 사용하거나 10회 이상 도구 호출을 완료한 후

디버그 정보: 온보딩이 비활성화되면 서버는 다음을 로그합니다: "Onboarding disabled via --no-homebound flag"

다양한 셸 사용

명령 실행에 사용할 셸을 지정할 수 있습니다:

// Using default shell (bash or system default)
execute_command({ "command": "echo $SHELL" })

// Using zsh specifically
execute_command({ "command": "echo $SHELL", "shell": "/bin/zsh" })

// Using bash specifically
execute_command({ "command": "echo $SHELL", "shell": "/bin/bash" })

이렇게 하면 셸별 특성을 사용하거나 여러 명령에 일관된 환경을 유지할 수 있습니다.

1. execute_command는 제한 시간 후 초기 출력이 반환됩니다

2. 명령은 백그라운드에서 계속 실행을 유지합니다

3. read_output와 PID를 사용하여 새 출력을 가져옵니다

4. 필요하면 force_terminate를 사용하여 실행하지 않도록 합니다

디버깅

서버를 디버깅해야 하는 경우 디버그 모드로 설치할 수 있습니다:

# Using npx
npx @wonderwhy-er/desktop-commander@latest setup --debug

# Or if installed locally
npm run setup:debug

이것은:

1. Claude가 별도의 "desktop-commander" 서버를 사용하도록 구성합니다

2. --inspect-brk=9229 플래그를 사용하여 Node.js inspector 프로토콜을 활성화

3. 디버거가 연결될 때까지 시작 지점에서 실행을 중지합니다

4. 추가 디버깅 환경 변수를 활성화

디버거 연결 방법:

• Chrome에서 chrome://inspect를 방문한 후 Node.js 인스턴스를 찾습니다.

• VS Code에서는 "Attach to Node Process" 디버그 구성을 사용합니다.

• 다른 IDE/도구에도 Node.js 디버깅을 위한 유사한 "연결(attach)" 옵션이 있을 수 있습니다.

중요한 디버깅 참고 사항:

• 서버는 디버거가 연결될 때까지 시작 시 일시 중지됩니다(--inspect-brk 플래그 때문).

• 디버깅 중에 활동이 보이지 않으면 올바른 Node.js 프로세스에 연결했는지 확인하세요.

• 여러 Node 프로세스가 실행 중일 수 있습니다. 포트 9229의 프로세스에 연결하세요.

• 디버그 서버는 Claude의 MCP 서버 목록에서 "desktop-commander-debug"로 식별됩니다.

문제 해결:

• 디버그 서버를 사용하는 동안 Claude가 시간 초과되면 디버거가 제대로 연결되지 않은 것일 수 있습니다.

• 제대로 연결되면 첫 번째 중단점에 도달한 후 프로세스가 계속 실행됩니다.

• 연결 후 IDE에서 추가 중단점을 설정할 수 있습니다.

Model Context Protocol 통합

이 프로젝트는 MCP Filesystem Server를 확장하여 다음을 지원합니다:

• Claude Desktop의 로컬 서버 지원

• 전체 시스템 명령 실행

• 프로세스 관리

• 파일 작업

• 검색/바꾸기 블록을 사용한 코드 편집

Claude MCP 탐구의 일환으로 제작되었습니다: https://youtube.com/live/TlbjFDbl5Us

Desktop Commander 지원하기

❤️ 후원자 명예의 전당

관대한 후원자들이 여기에 소개됩니다. 이 프로젝트를 가능하게 해 주셔서 감사합니다!

웹사이트

최신 정보, 문서, 업데이트를 보려면 공식 웹사이트 https://desktopcommander.app/을 방문하세요.

미디어

다음 자료를 통해 이 프로젝트에 대해 자세히 알아보세요:

기사

Claude with MCPs replaced Cursor & Windsurf. How did that happen? - Model Context Protocol 기능을 갖춘 Claude가 개발자 워크플로우를 어떻게 변화시키고 있는지 자세히 살펴봅니다.

비디오

Claude Desktop Commander Video Tutorial - Commander를 효과적으로 설정하고 사용하는 방법을 확인하세요.

AnalyticsIndiaMag 게재

This Developer Ditched Windsurf, Cursor Using Claude with MCPs

커뮤니티

도움이 필요하거나, 피드백을 공유하거나, 다른 사용자와 연결하려면 Discord 서버에 가입하세요.

사용자 후기

https://www.youtube.com/watch?v=ly3bed99Dy8\&lc=UgyyBt6\_ShdDX\_rIOad4AaABAg

문자 그대로 유튜브 댓글 처음 남겨요, 정말 감사합니다! 저는 오래된 Flutter 앱을 Cursor에서 이전 null-safety 버전에서 최신 버전으로 업데이트하는 데 어려움을 겪고 있었습니다. Claude 3.7으로 null-safety를 구현했지만 거의 다 되었는데 치명적인 BLE 오류가 있었고 며칠을 헤매도 해결하지 못했습니다. Augment Code도 시도했지만 마찬가지였습니다. 여러분의 MCP를 Claude Desktop에 설치하고 오래된 코드와 새 코드베이스를 완전히 비교하여 코드 업데이트를 반영하고 몇 시간 만에 문제를 해결했습니다. 시도하는 분들께 조언하자면, 원치 않는 변경 사항을 되돌릴 수 있도록 변경 사항을 스테이징하고 적절한 시점에 커밋하세요. 놀라워요! https://www.youtube.com/watch?v=ly3bed99Dy8\\\\&lc=UgztdHvDMqTb9jqnfl4AaABAg](https://www.youtube.com/watch?v=ly3bed99Dy8\\\\&lc=UgztdHvDMqTb9jqnfl4AaABAg)

좋아요! 저는 일주일 전에 Windsurf를 구매해서 사용했습니다. 오래된 풀스택 socket 프로젝트를 업그레이드하는 데 많은 경우에 제대로 되지만 자주 cascade로 오용되어 모든 변경을 되돌리고 수백 개의 cascade 토큰을 잃는 일이 많았습니다. 일주일 만에 100개 미만으로 줄었고 10$에 300개만 사고 싶지 않았습니다. 이 Claude MCP를 사용하면서 드디어 필요한 Claude Pro에 가입하게 되었고, ChatGPT의 대안으로도 훌륭한 이유가 생겼습니다. 이제는 토큰 비용 걱정 없이 원하는 만큼 코드를 작성할 수 있습니다. 또한 이는 단순한 코드 편집기 그 이상입니다. 좋은 영상 감사합니다! https://www.youtube.com/watch?v=ly3bed99Dy8\\\\&lc=UgyQFTmYLJ4V8wIlmql4AaABAg](https://www.youtube.com/watch?v=ly3bed99Dy8\\\\&lc=UgyQFTmYLJ4V8wIlmql4AaABAg)

훌륭한 도구입니다. 감사합니다. Claude가 수술처럼 정밀한 편집을 할 수 있게 해 주고 사람 개발자처럼 알려줍니다. https://www.youtube.com/watch?v=ly3bed99Dy8\\\\&lc=Ugy4-exy166\\\\_Ma7TH-h4AaABAg](https://www.youtube.com/watch?v=ly3bed99Dy8\\\\&lc=Ugy4-exy166_Ma7TH-h4AaABAg)

당신은 정말 저의 영웅입니다. 제 최근 경험을 제가 할 수 있는 것보다 훨씬 잘 요약하고십니다. Cursor와 Windsurf 둘 다 화면에 소리 지를 정도로 답답했습니다. 우연히 Claude를 직접 사용하면 어떨까 생각했고, 그 이후로는 돌아보지 않았습니다. Claude를 먼저 이용해 제 정신을 유지하고, 필요한 경우 다른 IDE, 프레임워크 등을 사용합니다. 혼자인 줄 알았는데 저만 그런 게 아니어서 좋네요 haha. 33 1 https://medium.com/@pharmx/you-sir-are-my-hero-62cff5836a3e](https://www.youtube.com/watch?v=ly3bed99Dy8&lc=Ugy4-exy166_Ma7TH-h4AaABAg)

이 프로젝트가 유용하다고 생각된다면 GitHub에서 ⭐ 스타를 눌러 주세요 다른 사람들이 이 프로젝트를 발견하고 개발이 계속되는 데 도움이 됩니다.

커뮤니티의 기여를 환영합니다! 버그를 발견했든, 기능 요청이든, 코드를 기여하려든, 다음과 같이 하실 수 있습니다:

• 버그를 발견하셨나요? github.com/wonderwhy-er/DesktopCommanderMCP/issues에서 이슈를 등록하세요.

• 기능 아이디어가 있으신가요? 이슈 섹션에 기능 요청을 제출하세요.

• 코드를 기여하고 싶으신가요? 저장소를 포크하고, 브랜치를 만들고, 풀 리헤스트를 제출하세요.

• 질문이나 토론이 있으신가요? GitHub 토론 탭에서 대화를 시작하세요.

크든 작든 모든 기여에 크게 감사드립니다!

이 도구가 작업 흐름에 유용하다고 생각하시면 프로젝트 지원하기를 고려해 주세요.

자주 묻는 질문

일반적인 질문에 대한 답변입니다. 더 포괄적인 FAQ는 자세한 FAQ 문서를 참조하세요.

Desktop Commander란 무엇인가요?

Claude Desktop이 파일 시스템과 터미널에 접근할 수 있게 해 주는 MCP 도구로, Claude를 코딩, 자동화, 코드베이스 탐색 등에 다 가기 위해 도구로 만듭니다.

Cursor/Windsurf와 어떻게 다른가요?

IDE 중심의 도구들과 달리 Claude Desktop Commander는 코딩 환경 안에서만 동작한 해결책 중심의 접근 방식을 제공합니다. Claude는 파일을 청크로 나누지 않고 전체로 읽으며, 여러 프로젝트를 동시에 작업할 수 있고, 끊임없는 검안 필요한 방식으로 변경을 수행합니다.

API 크레딧을 사용해야 하나요?

아니요. 이 도구는 API 호출이 아니라 Claude Desktop의 표준 Pro 구독($20/월)으로 작동하므로 구독 외의 추가 비용은 없습니다.

Desktop Commander는 자동으로 업데이트되나요?

네, npx 또는 Smithery로 설치된 경우, Claude를 다시 시작할 때 Desktop Commander가 최신 버전으로 자동 업데이트됩니다. 수동으로 업데이트할 필요는 없습니다.

가장 일반적인 사용 사례는 무엇인가요?

• 복잡한 코드베이스 탐색와 파악

• 다이어그램 및 문서 생성

• 시스템 전반의 작업 자동화

• 여러 프로젝트에서 동시에 작업

• 정밀한 제어로 수술적 코드 변경

도구 설치 또는 사용에 문제가 있습니다. 어디서 도움부터 받을 수 있나요?

커뮤니티 지원이 필요하면 Discord 서버에 가입하고, 알려진 문제는 GitHub 이슈, 문제 해결 방법은 전체 FAQ를 참조하세요. 보다 사용자 친화적인 경험을 위해 웹사이트 FAQ 섹션을 방문할 수도 있습니다. 새로운 문제가 발생하면 GitHub 이슈 등록에 문제에 대한 세부 정보와 함께 등록해 주세요.

보안 취약점을 어떻게 신고하나요?

발견한 보안 취약점에 대한 자세한 정보를 GitHub 이슈로 등록해 주세요. 책임 있는 공개에 대한 전체 지침은 보안 정책을 참조하세요.

데이터 수집 및 개인정보 보호

Desktop Commander는 도구를 개선하기 위해 제한된 가명 기반 텔레메트리를 수집합니다. 파일 내용, 파일 경로, 명령 인수는 수집하지 않습니다.

수신 거부: Claude에게 "disable Desktop Commander telemetry"라고 요청하거나 구성 파일에서 "telemetryEnabled": false로 설정하세요.

자세한 내용은 개인정보 처리방침을 참조하세요.

검증

라이선스

MIT