Desktop Commander (MCP server) — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

diff 방식 편집을 위한 정밀한 edit_block 도구 — 파일 전체 재작성 불필요
타임아웃과 백그라운드 프로세스 추적이 포함된 터미널 명령
Claude가 워크스페이스를 벗어나지 못하도록 설정 가능한 allowed_directories
ripgrep 수준의 속도로 파일 검색
스크린샷 및 디자인 파일을 위한 이미지 읽기 지원

라이브 데모

실제 사용 모습

desktop-commander-mcp.replay ▶ 준비됨

0/0

설치

클라이언트 선택

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

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

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

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

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

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

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "desktop-commander-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@wonderwhy-er/desktop-commander"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

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

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Desktop Commander

Cursor나 Claude Code 없이 Claude Desktop을 무료 코딩 에이전트로 사용하기

👤 IDE 구독 없이 에이전트 코딩을 원하는 개발자 ⏱ ~20 min beginner

언제 쓸까: 이미 Claude Desktop이 있고, 코드 스니펫 붙여넣기가 아닌 실제 레포 편집을 원할 때.

사전 조건

Claude Desktop 설치 — claude.ai/download에서 다운로드
작업 디렉토리 허용 목록 등록 — 최초 실행 시 Claude가 접근할 수 있는 디렉토리를 지정

흐름

설치 및 워크스페이스 잠금

Install desktop-commander. Limit it to ~/Code/myproject — nothing outside.✓ 복사됨

→ 설정에 allowed_directories 제한이 반영되고 Claude에서 도구 목록이 표시됨
실제 변경사항 적용

Open ~/Code/myproject. Find every TODO comment, group by file, propose fixes for the top 5.✓ 복사됨

→ ripgrep 속도의 스캔, 줄 번호가 포함된 우선순위 목록
edit_block으로 적용

Apply the proposed fixes using edit_block. Don't rewrite whole files — just the necessary diffs.✓ 복사됨

→ 각 편집에 old_string/new_string 블록이 표시되고, 이후 깔끔한 git diff 확인

결과: Claude Desktop이 유료 IDE 어시스턴트와 동일한 품질로 레포에 실제 코드 변경사항을 작성합니다.

함정

allowed_directories 미설정 시 Claude가 홈 폴더 전체를 스캔 — ~/.claude-server-commander/config.json을 수정하고 Claude Desktop을 재시작

함께 쓰기: github · filesystem

채팅을 블로킹하지 않고 개발 서버를 실행하며 출력 캡처하기

👤 멀티 프로세스 환경을 디버깅하는 개발자 ⏱ ~25 min intermediate

언제 쓸까: Claude가 서버를 시작하고, 별도 터미널에서 테스트를 실행하며, 동시에 로그를 tail해야 할 때.

흐름

서버를 백그라운드로 시작

Start npm run dev as a background process. Show me the PID.✓ 복사됨

→ 프로세스 시작, PID 반환, 출력 스트리밍 캡처
서버 실행 중 테스트 수행

While that's running, execute the e2e suite and surface any failures.✓ 복사됨

→ 테스트가 독립적으로 실행되고 서버는 계속 스트리밍됨
온디맨드 로그 검사

Show the last 100 lines of stdout from PID 12345. Anything red?✓ 복사됨

→ 에러가 강조된 로그 슬라이스

결과: Claude에서 완전히 오케스트레이션된 멀티 프로세스 디버깅 세션.

함정

채팅 종료 후에도 백그라운드 프로세스가 계속 실행됨 — 완료 후 kill_process 도구를 사용하거나 Claude Desktop 재시작

한 세션에서 수백 개의 파일을 일괄 리팩토링하기

👤 코드베이스 전체 마이그레이션(예: 이름 변경, 지원 종료)을 수행하는 개발자 ⏱ ~60 min intermediate

언제 쓸까: IDE 어시스턴트가 50개 이상 파일 변경에서 버벅거릴 때, 한 번의 오케스트레이션 패스를 원할 때.

흐름

변경 범위 파악

Find every import of oldLib. Group by file and tell me how many changes per file.✓ 복사됨

→ 파일별 영향도 히스토그램
한 파일로 먼저 테스트

Apply the migration to the smallest-impact file as a smoke test.✓ 복사됨

→ 단일 파일 마이그레이션 완료, 테스트 통과
배치 단위로 롤아웃

Now apply to the next 20 files. After each batch, run lint and tell me if anything breaks.✓ 복사됨

→ 배치별 진행 보고와 상태 체크

결과: 검증 가능한 배치별 체크포인트와 함께 코드베이스 전체 마이그레이션 완료.

함정

공백 차이로 edit_block 실패 — 까다로운 패턴에는 search-replace 모드 사용, 줄 바꿈 모드 확인

함께 쓰기: github

조합

다른 MCP와 조합해 10배 효율

desktop-commander-mcp + github

로컬 편집 후 PR 생성

Apply the fixes via desktop-commander, then use github MCP to open a PR with a clean summary.✓ 복사됨

desktop-commander-mcp + filesystem

샌드박스된 파일시스템 접근 방식 비교

Use filesystem MCP for read-only library scans and desktop-commander for actual project edits.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출
execute_command	command: str, timeout_ms?: int	git, npm, 빌드 스크립트 등 모든 셸 작업
edit_block	file_path, old_string, new_string	파일 전체 재작성 없이 정밀한 편집이 필요할 때
read_file	path	컨텍스트 파악을 위해 소스 읽기
write_file	path, content	새 파일 생성
search_files	path, pattern	이름/glob으로 파일 찾기
search_code	pattern, path?	파일 전체에서 내용 검색
list_processes	()	세션에서 실행 중인 프로세스 확인

비용 및 제한

운영 비용

API 쿼터: 해당 없음 — 로컬
호출당 토큰: 가변적 — 큰 파일은 토큰을 많이 소모
금액: 무료 (MIT)
팁: 몇 줄만 필요할 때는 read_file 대신 search_code 사용

보안

권한, 시크릿, 파급범위

최소 스코프: filesystem-read filesystem-write shell-exec

자격 증명 저장: 없음 — 모두 로컬

데이터 외부 송신: 없음 — 모든 호출이 로컬

절대 부여 금지: Unrestricted root directory access

execute_command는 무엇이든 실행 가능 — allowed_directories를 엄격히 유지
~/.ssh 또는 자격증명 디렉토리에 접근 권한을 부여하지 마세요

문제 해결

자주 발생하는 오류와 해결

edit_block에서 권한 거부

~/.claude-server-commander/config.json의 allowed_directories에 해당 디렉토리 추가

확인: cat the config and restart Claude Desktop

프로세스가 시작되었지만 출력이 없음

PID와 함께 read_output 사용; 출력은 기본적으로 채팅에 스트리밍되지 않고 버퍼링됨

edit_block이 'old_string not found' 보고

공백 또는 줄 바꿈 불일치 — 정확한 바이트를 복사하려면 먼저 파일을 다시 읽기

대안

Desktop Commander 다른 것과 비교

대안	언제 쓰나	단점/장점
Claude Code (CLI)	플래닝이 포함된 Anthropic 공식 에이전트 루프를 원할 때	Claude Code는 더 세련되어 있지만 별도 구독이 필요; Desktop Commander는 무료
filesystem (official MCP)	셸 실행 없이 읽기 전용 또는 샌드박스된 파일 접근이 필요할 때	더 작은 범위, 명령 실행 불가

Desktop Commander