Desktop Commander MCP
- 추천0
- GitHub 별10K
- 개발라이선스MIT
터미널 명령 실행, 파일 읽기·쓰기·검색, 코드 편집, Excel·PDF·DOCX 처리를 AI에 맡기는 MCP 서버. MIT
설치 방법은 설치 탭에 정리했어요.
설명
Desktop Commander MCP
AI로 파일을 검색·수정·관리하고 터미널 명령을 실행하세요
코드와 텍스트를 다루고, 프로세스를 실행하고, 작업을 자동화합니다. 다른 AI 에디터를 훨씬 넘어서는 일을 하면서도, API 토큰 비용 대신 쓰고 있는 클라이언트 구독을 그대로 씁니다.
목차
- 기능
- 설치 방법
- 시작하기
- 사용법
- 파일 미리보기 UI와 마크다운 편집기
- 오래 걸리는 명령 다루기
- 진행 중인 작업과 할 일
- 후원
- 웹사이트
- 미디어
- 사용 후기
- 자주 묻는 질문
- 기여하기
- 라이선스
모든 개발 도구를 한곳에. Desktop Commander는 모든 개발 도구를 하나의 채팅 안에 모아 줍니다. 내 컴퓨터에서 오래 걸리는 터미널 명령을 실행하고, Model Context Protocol(MCP)로 프로세스를 관리하세요. MCP Filesystem Server를 바탕으로 만들었고, 검색·바꾸기 방식의 파일 편집 기능을 더했습니다.
기능
- 원격 AI 제어 - 원격 MCP로 ChatGPT, Claude 웹 등 다른 AI 서비스에서도 Desktop Commander를 쓸 수 있습니다
- 파일 미리보기 UI - Claude Desktop에서 마크다운 렌더링, 인라인 이미지, 펼쳐지는 내용, 내장 마크다운 편집기, 「폴더에서 열기」를 제공합니다
- 대화형 프로세스 제어가 되는 향상된 터미널 명령
- 파일을 저장하지 않고 메모리에서 코드 실행(Python, Node.js, R)
- 즉석 데이터 분석 - CSV · JSON · Excel 파일을 분석해 달라고 요청만 하면 됩니다
- Excel 파일 기본 지원 - 외부 도구 없이 Excel 파일(.xlsx, .xls, .xlsm)을 읽고 쓰고 고치고 검색합니다
- PDF 지원 - 텍스트를 뽑아 읽고, 마크다운으로 새 PDF를 만들고, 기존 PDF를 고칩니다
- DOCX 지원 - Word 문서(.docx)를 읽고 만들고 고치고 검색합니다. XML을 정밀하게 고치고 마크다운을 DOCX로 변환합니다
- 실행 중인 프로세스와 상호작용(SSH, 데이터베이스, 개발 서버)
- 출력을 스트리밍하는 터미널 명령 실행
- 명령 제한 시간과 백그라운드 실행 지원
- 프로세스 관리(목록 보기와 종료)
- 오래 걸리는 명령을 위한 세션 관리
- 프로세스 출력 페이지 나누기 - offset · length로 터미널 출력을 읽어 컨텍스트가 넘치는 것을 막습니다
- 서버 설정 관리:
- 설정 값 읽기와 쓰기
- 여러 설정을 한 번에 바꾸기
- 서버를 다시 켜지 않고 설정을 바로 바꾸기
- 전체 파일 시스템 작업:
- 파일 읽기와 쓰기(텍스트, Excel, PDF, DOCX)
- 디렉터리 만들기와 목록 보기
- 재귀 디렉터리 목록 - 깊이를 정할 수 있고, 큰 폴더에서 컨텍스트가 넘치지 않게 막아 줍니다
- 파일과 디렉터리 옮기기
- 파일과 내용 검색(Excel 내용 포함)
- 파일 메타데이터 읽기
- 음수 offset으로 파일 끝에서 읽기: Unix의 tail처럼 음수 offset으로 파일 끝부터 읽습니다
- 코드 편집 기능:
- 작은 수정을 위한 정밀한 텍스트 바꾸기
- 큰 수정을 위한 파일 전체 다시 쓰기
- 여러 파일 지원
- 패턴 기반 바꾸기
- vscode-ripgrep으로 폴더 안의 코드·텍스트를 재귀 검색
- 로컬 도구 호출 기록과 감사 로그:
- 도구 호출과 인자는 Desktop Commander가 돌아가는 컴퓨터에 로컬로 기록됩니다
get_recent_tool_calls로 출력 미리보기가 제한된 최근 호출 기록을 볼 수 있습니다- 크기 기준으로 파일을 돌려 쓰고 잘라 내서 기록 파일이 커지지 않게 합니다
- 안전 장치(샌드박스가 아닙니다 — SECURITY.md 참고):
- 파일 작업에서 심볼릭 링크 우회 방지
- 실수로 실행하는 것을 막는 명령 차단 목록
- 완전한 격리를 위한 Docker 격리
설치 방법
ChatGPT, Claude 웹 등 원격 클라이언트는 원격 장치 실행기를 보세요. Node.js가 없으면 설치한 뒤 macOS · Linux · Windows에서 Desktop Commander Remote를 실행합니다.
Claude Desktop에 설치
Claude Desktop에는 여러 설치 방법이 있습니다.
📋 업데이트와 제거 안내: 방법 1, 2, 3, 4, 6은 자동으로 업데이트됩니다. 방법 5는 직접 업데이트해야 합니다.
방법 1: npx로 설치 ⭐ 자동 업데이트 (Node.js 필요)
터미널에서 실행하세요.
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를 실행하세요
방법 2: bash 스크립트 설치 (macOS) ⭐ 자동 업데이트 (필요하면 Node.js도 설치)
저장소의 install.sh를 실행하면 의존성과 설정을 자동으로 처리합니다. 스크립트 내용은 install.sh에서 먼저 확인할 수 있습니다.
✅ 자동 업데이트: 예
🔄 수동 업데이트: 설치 명령을 다시 실행하세요
🗑️ 제거: npx @wonderwhy-er/desktop-commander@latest remove를 실행하세요
방법 3: Smithery로 설치 ⭐ 자동 업데이트 (Node.js 필요)
- 방문: https://smithery.ai/server/@wonderwhy-er/desktop-commander
- 아직이라면 Smithery에 로그인하세요
- 오른쪽에서 클라이언트를 선택하세요(Claude Desktop)
- 클라이언트를 선택하면 나오는 키로 설치하세요
- Claude Desktop을 다시 켜세요
✅ 자동 업데이트: 예 - Claude를 다시 켤 때 자동으로 업데이트됩니다 🔄 수동 업데이트: Smithery 페이지에서 다시 설치하세요
방법 4: claude_desktop_config에 직접 추가 ⭐ 자동 업데이트 (Node.js 필요)
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에서 항목을 지우세요
방법 5: 로컬에 체크아웃 ❌ 수동 업데이트 (Node.js 필요)
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 서버 항목을 지우세요
방법 6: Docker 설치 🐳 ⭐ 자동 업데이트 (Node.js 불필요)
격리가 필요하거나 Node.js가 없는 사용자에게 알맞습니다. 작업 환경이 유지되는 샌드박스 Docker 컨테이너에서 실행합니다.
준비물: Docker Desktop이 설치되어 실행 중이어야 하고, Claude Desktop 앱이 설치되어 있어야 합니다.
설치 스크립트는 install-docker.sh(macOS · Linux)와 install-docker.ps1(Windows)입니다. Docker를 확인하고, 이미지를 받고, 마운트할 폴더를 묻고, Claude Desktop을 설정합니다. 스크립트는 저장소에서 먼저 확인할 수 있습니다: install-docker.sh · install-docker.ps1
Docker 유지: 도구, 설정, 작업 파일, 패키지 캐시가 재시작해도 남습니다.
직접 설정하는 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"
]
}
}
}
✅ 자동 업데이트: 예 - 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 설정 파일에 넣으세요.
Cursor
~/.cursor/mcp.json(전역) 또는 프로젝트 폴더의 .cursor/mcp.json(프로젝트 전용)에 직접 추가하세요.
Windsurf
~/.codeium/windsurf/mcp_config.json에 추가하세요.
VS Code / GitHub Copilot
프로젝트의 .vscode/mcp.json 또는 VS Code 사용자 설정(JSON)에 추가하세요. Chat > MCP가 켜져 있어야 합니다. 에이전트 모드에서 동작합니다.
Cline
VS Code의 Cline 확장 설정에서 구성하세요. Cline 사이드바에서 MCP Servers 아이콘을 누르고 위의 JSON 설정을 추가하세요.
Roo Code
Roo Code의 MCP 설정 파일에 추가하세요.
Claude Code
claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest
현재 프로젝트에만 설치하려면 --scope user를 빼세요.
Trae
「Add manually」기능으로 위의 JSON 설정을 붙여 넣으세요.
Kiro
Kiro > MCP Servers에서 + Add를 누르고 위의 JSON 설정을 붙여 넣으세요.
Codex (OpenAI)
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"]
JetBrains (AI Assistant)
JetBrains IDE에서 Settings → Tools → AI Assistant → Model Context Protocol (MCP) 로 가서 + Add를 누르고 As JSON을 고른 뒤 위의 JSON 설정을 붙여 넣으세요.
Gemini CLI
~/.gemini/settings.json에 추가하세요.
{
"mcpServers": {
"desktop-commander": {
"command": "npx",
"args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
}
}
}
Augment Code
Cmd/Ctrl+Shift+P로 Augment 패널을 열고 desktop-commander라는 이름의 MCP 서버를 위의 JSON 설정으로 추가하세요.
Qwen Code
아래 명령으로 Desktop Commander를 추가하세요.
qwen mcp add desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest
또는 .qwen/settings.json(프로젝트) 또는 ~/.qwen/settings.json(전역)에 추가하세요.
ChatGPT / Claude 웹 (원격 MCP)
명령은 내 컴퓨터에서 실행하면서 ChatGPT, Claude 웹 등 AI 서비스에서 Desktop Commander를 쓸 수 있습니다.
원격 장치를 시작하세요.
npx @wonderwhy-er/desktop-commander@latest remote
처음 실행하면 브라우저 인증을 마치고, mcp.desktopcommander.app에서 AI를 연결하세요.
Ctrl+C로 로컬 장치를 잠시 멈출 수 있습니다npx @wonderwhy-er/desktop-commander@latest remote --help로 사용할 수 있는 CLI 옵션을 볼 수 있습니다
보안
- ✅ 원격 장치는 실행 중일 때만 명령을 받습니다
- ✅ 명령은 내 사용자 권한으로 로컬에서 실행됩니다
- ✅ 안전한 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 설정에서 지우기
-
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
- macOS:
-
설정 파일 고치기:
- 텍스트 편집기로 파일을 엽니다
"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는 초보자용 실습 예제를 보여 줍니다.
- 📁 다운로드 폴더 자동 정리
- 📊 Python으로 CSV · Excel 파일 분석
- ⚙️ GitHub Actions CI/CD 설정
- 🔍 코드베이스 둘러보고 이해하기
- 🤖 대화형 개발 환경 실행
사용법
서버는 여러 범주로 나뉜 도구 모음을 제공합니다.
사용할 수 있는 도구
| 범주 | 도구 | 설명 |
|---|---|---|
| 설정 | get_config | 서버 설정 전체를 JSON으로 가져옵니다(blockedCommands, defaultShell, allowedDirectories, fileReadLineLimit, fileWriteLineLimit, telemetryEnabled 포함) |
set_config_value | 키로 설정 값 하나를 바꿉니다. 바꿀 수 있는 설정: • blockedCommands: 실행할 수 없는 셸 명령 배열 • defaultShell: 명령에 쓸 셸(예: bash, zsh, powershell) • allowedDirectories: 파일 작업에 쓸 수 있는 파일 시스템 경로 배열(⚠️ 터미널 명령은 이 디렉터리 밖의 파일에도 접근할 수 있습니다) • fileReadLineLimit: 한 번에 읽을 최대 줄 수(기본 1000) • fileWriteLineLimit: 한 번에 쓸 최대 줄 수(기본 50) • telemetryEnabled: 텔레메트리 켜기/끄기(불리언) | |
| 터미널 | start_process | 입력을 받을 준비가 되었는지 똑똑하게 알아채며 프로그램을 시작합니다 |
interact_with_process | 실행 중인 프로그램에 명령을 보내고 응답을 받습니다 | |
read_process_output | 실행 중인 프로세스의 출력을 읽습니다 | |
force_terminate | 실행 중인 터미널 세션을 강제로 끝냅니다 | |
list_sessions | 활성 터미널 세션을 모두 보여 줍니다 | |
list_processes | 실행 중인 프로세스를 자세한 정보와 함께 모두 보여 줍니다 | |
kill_process | PID로 실행 중인 프로세스를 끝냅니다 | |
| 파일 시스템 | read_file | 로컬 파일 시스템, URL, Excel 파일(.xlsx, .xls, .xlsm), PDF에서 내용을 읽습니다. 줄/쪽 기준으로 나누어 읽을 수 있습니다 |
read_multiple_files | 여러 파일을 동시에 읽습니다 | |
write_file | 다시 쓰기 또는 덧붙이기 모드로 파일 내용을 씁니다. Excel 파일(JSON 2차원 배열 형식)을 지원합니다. PDF는 write_pdf를 쓰세요 | |
write_pdf | 마크다운으로 새 PDF를 만들거나 기존 PDF를 고칩니다(쪽 삽입/삭제). HTML/CSS 스타일과 SVG 그래픽을 지원합니다 | |
create_directory | 새 디렉터리를 만들거나 있는지 확인합니다 | |
list_directory | 파일과 디렉터리의 자세한 재귀 목록을 가져옵니다(depth 매개변수 지원, 기본 depth=2) | |
move_file | 파일과 디렉터리를 옮기거나 이름을 바꿉니다 | |
start_search | 파일 이름이나 내용 패턴으로 파일을 스트리밍 검색합니다(텍스트 파일과 Excel 내용 검색) | |
get_more_search_results | 진행 중인 검색의 결과를 offset으로 나누어 가져옵니다 | |
stop_search | 진행 중인 검색을 부드럽게 멈춥니다 | |
list_searches | 진행 중인 검색 세션을 모두 보여 줍니다 | |
get_file_info | 파일이나 디렉터리의 자세한 메타데이터를 가져옵니다(Excel 파일은 시트 정보 포함) | |
| 텍스트 편집 | edit_block | 텍스트 파일은 정해진 부분만 바꾸고, Excel 파일은 범위 기준으로 셀을 고칩니다 |
| 분석 | get_usage_stats | 내가 참고할 사용 통계를 가져옵니다 |
get_recent_tool_calls | 디버깅과 맥락 복구를 위해 인자와 출력이 담긴 최근 도구 호출 기록을 가져옵니다 | |
give_feedback_to_desktop_commander | Desktop Commander 팀에 의견을 보내는 양식을 브라우저에서 엽니다 |
간단한 예
데이터 분석:
「sales.csv를 분석해서 상위 고객을 보여 줘」 → Claude가 메모리에서 Python 코드를 실행
원격 접속:
「내 서버에 SSH로 접속해서 디스크 용량 확인해 줘」 → Claude가 SSH 세션을 유지
개발:
「Node.js를 켜서 이 API를 테스트해 줘」 → Claude가 대화형 Node 세션을 실행
도구 사용 예
검색/바꾸기 블록 형식:
filepath.ext
<<<<<<< SEARCH
찾을 내용
=======
새 내용
>>>>>>> REPLACE
예:
src/main.js
<<<<<<< SEARCH
console.log("old message");
=======
console.log("new message");
>>>>>>> REPLACE
향상된 edit_block 기능
edit_block 도구는 신뢰도를 높이는 여러 개선이 들어 있습니다.
- 개선된 프롬프트: 도구 설명이 큰 변경 하나보다 작고 집중된 수정 여러 개를 하도록 안내합니다
- 퍼지 검색 대체: 정확히 일치하지 않으면 퍼지 검색을 하고 자세한 결과를 알려 줍니다
- 글자 단위 diff:
{-지운 것-}{+더한 것+}형식으로 무엇이 다른지 정확히 보여 줍니다 - 여러 번 나오는 경우 지원:
expected_replacements매개변수로 여러 곳을 바꿀 수 있습니다 - 자세한 로그: 모든 퍼지 검색을 기록해 분석과 디버깅에 씁니다
검색이 실패하면 가장 가까운 일치 항목의 유사도, 실행 시간, 글자 차이를 포함한 자세한 정보가 나옵니다. 이 내용은 나중에 퍼지 검색 로그 도구로 분석할 수 있게 자동으로 기록됩니다.
Docker 지원
🐳 격리된 환경에서 쓰기
Desktop Commander는 Docker 컨테이너에서 실행할 수 있어 호스트 시스템과 완전히 격리되고 컴퓨터에는 위험이 없습니다. 테스트, 개발, 완전한 샌드박스가 필요할 때 알맞습니다.
설치 안내
-
Windows/Mac용 Docker 설치
- docker.com에서 Docker Desktop을 내려받아 설치하세요
-
Desktop Commander Docker 구성 받기
- 방문: https://hub.docker.com/mcp/server/desktop-commander/manual
- 방법 A: 제공되는 터미널 명령으로 자동 설정
- 방법 B: 「Standalone」을 눌러 구성 JSON을 받아 Claude Desktop 설정에 직접 추가
-
내 컴퓨터 폴더 마운트 (곧 제공)
- 로컬 디렉터리를 Docker 컨테이너에 마운트하는 방법은 곧 안내됩니다
- 완전한 격리를 유지하면서 내 파일을 쓸 수 있게 됩니다
Docker 사용의 장점
- 호스트 시스템과 완전한 격리
- 컴퓨터가 달라도 일관된 환경
- 쉬운 정리 - 다 쓰면 컨테이너만 지우면 됩니다
- 새 기능이나 설정을 시험하기에 알맞음
URL 지원
read_file은 로컬 파일과 URL에서 모두 내용을 가져올 수 있습니다- 예:
read_file에isUrl: true매개변수를 주면 웹 자원을 읽습니다 - 텍스트와 이미지 내용을 모두 처리합니다
- 이미지(로컬 또는 URL)는 Claude 화면에 텍스트가 아니라 그림으로 보입니다
- Claude가 실제 이미지 내용을 보고 분석할 수 있습니다
- URL 요청의 기본 제한 시간은 30초입니다
파일 미리보기 UI와 마크다운 편집기
Desktop Commander에는 AI가 파일을 다루는 동안 파일을 화면에 그려 주는 풍부한 파일 미리보기 위젯이 Claude Desktop에 들어 있습니다.
지원하는 파일 형식
- 마크다운 — 내장 편집기가 있는 렌더링 미리보기
- 이미지 — 인라인 표시(PNG, JPEG, GIF, WebP 등)
- 코드 파일 — 문법 강조가 되는 소스 보기
- HTML — 소스 보기로 전환할 수 있는 렌더링 미리보기
- 디렉터리 — 접고 펼치며 필요할 때 불러오는 대화형 트리
- PDF, Excel, DOCX — 내용을 바로 뽑아서 표시
마크다운 편집기
Claude Desktop에서 .md 파일을 볼 때 따로 앱을 열지 않고 미리보기 패널 안에서 바로 고칠 수 있습니다.
사용 방법:
- Claude에게 마크다운 파일을 읽거나 만들어 달라고 합니다
- ⤢ Expand 단추로 파일 미리보기를 전체 화면으로 펼칩니다
- 전체 화면에서 편집기가 자동으로 켜집니다
- 실시간 미리보기 전환, 복사, 되돌리기, 저장 컨트롤로 내용을 고칩니다
- 변경은 디스크에 저장되고, 접으면 인라인 보기로 돌아갑니다
편집기 기능:
- 실시간 편집 / 미리보기 전환 — 원본 마크다운과 렌더링 결과를 오갑니다
- 저장 상태 표시가 있는 디스크 자동 저장
- 저장하지 않은 변경을 되돌리는 되돌리기
- 마크다운 원본 전체를 가져가는 복사 단추
- 패널에서 기본 마크다운 앱을 바로 여는 편집기에서 열기
- 부분 읽기 인식 — 파일의 일부만 읽었을 때 주변 줄을 불러와 합칩니다
- 텍스트 선택 맥락 — 미리보기에서 텍스트를 선택하면 AI가 선택한 부분을 참고합니다
디렉터리 탐색기
Claude가 list_directory를 실행하면 결과가 미리보기 패널 안의 대화형 파일 트리로 열립니다. 텍스트 출력만 나오지 않습니다.
기능:
- 펼칠 수 있는 트리 — 폴더를 눌러 접고 펼칩니다. 최상위 내용은 바로 보입니다
- 지연 불러오기 — 하위 폴더는 필요할 때 불러와 처음 화면이 빠릅니다
- 큰 디렉터리 처리 — 항목이 많은 디렉터리는 화면을 덮는 대신
⚠ click to load all단추를 보여 줍니다 - Finder/탐색기에서 열기 — 폴더마다 파일 관리자에서 위치를 보여 주는 단추가 있습니다
- 눌러서 미리보기 — 트리의 파일을 누르면 파일 미리보기 패널에서 바로 열립니다
- 뒤로 가기 — 트리에서 파일을 연 뒤 ← Back 단추로 디렉터리 보기로 돌아갑니다
그 밖의 미리보기 기능
- 펼치기 / 접기 — 간단한 요약 줄과 전체 패널을 오갑니다
- 폴더에서 열기 — 파일 위치를 Finder/탐색기에서 한 번에 보여 줍니다
- 줄 더 불러오기 — 일부만 읽은 구간의 위아래 내용을 이어서 불러옵니다
- 텍스트 선택 — 미리보기에서 텍스트를 강조하면 AI가 그 부분을 보고 참고합니다
퍼지 검색 로그 분석 (npm 스크립트)
퍼지 검색 로그 시스템에는 MCP 환경 밖에서 로그를 분석하는 npm 스크립트가 있습니다.
# 최근 퍼지 검색 로그 보기
npm run logs:view -- --count 20
# 패턴과 성능 분석
npm run logs:analyze -- --threshold 0.8
# 로그를 CSV 또는 JSON으로 내보내기
npm run logs:export -- --format json --output analysis.json
# 로그 모두 지우기(확인 후)
npm run logs:clear
스크립트 문서는 scripts/README.md를 보세요.
퍼지 검색 로그
Desktop Commander는 edit_block 도구의 퍼지 검색 작업을 자세히 기록합니다. 정확히 일치하는 부분을 찾지 못하면 퍼지 검색을 하고 분석용 정보를 남깁니다.
기록하는 내용
퍼지 검색마다 기록합니다.
- 찾은 텍스트와 검색한 텍스트: 찾으려던 것과 실제로 찾은 것
- 유사도 점수: 일치에 얼마나 가까운지(0-100%)
- 실행 시간: 검색에 걸린 시간
- 글자 차이: 정확히 무엇이 다른지 보여 주는 자세한 diff
- 파일 메타데이터: 확장자, 검색한 글과 찾은 글의 길이
- 글자 코드: 차이를 만든 특정 글자 코드
로그 위치
로그는 자동으로 저장됩니다.
- macOS/Linux:
~/.claude-server-commander-logs/fuzzy-search.log - Windows:
%USERPROFILE%\.claude-server-commander-logs\fuzzy-search.log
알 수 있는 것
퍼지 검색 로그로 다음을 알 수 있습니다.
- 정확한 일치가 실패하는 이유: 공백 차이, 줄바꿈, 문자 인코딩 같은 흔한 원인
- 성능 패턴: 검색이 복잡할수록 실행 시간이 어떻게 달라지는지
- 파일 형식 문제: 어떤 확장자에서 일치 문제가 자주 생기는지
- 문자 인코딩 문제: 차이를 만드는 특정 글자 코드
로컬 도구 기록과 감사 로그
Desktop Commander는 도구 호출 기록을 MCP 서버가 돌아가는 컴퓨터에 로컬로 남깁니다. 이 로컬 파일은 선택 사항인 텔레메트리와 별개이며, 서버 쪽의 과거 감사 로그가 아닙니다.
claude_tool_call.log — 로컬 인자 로그
로컬 MCP 서버가 처리한 도구 호출마다 ISO 시각, 도구 이름, JSON으로 만든 인자가 한 줄로 덧붙습니다. 인자는 이 로컬 파일에 쓰기 전에 가리거나 걸러지지 않으므로 명령 텍스트, 파일 경로, 도구에 넘긴 민감한 값이 들어 있을 수 있습니다. 도구 출력은 이 파일에 쓰이지 않습니다.
활성 파일은 10 MB가 되면 돌려 씁니다. 이전 파일은 claude_tool_call_2026-09-07_14-32-10.log처럼 시각이 붙은 이름으로 바뀌고 새 claude_tool_call.log가 만들어집니다. 돌려 쓴 파일은 로거가 자동으로 지우지 않습니다.
위치:
- macOS/Linux:
~/.claude-server-commander/claude_tool_call.log - Windows:
%USERPROFILE%\.claude-server-commander\claude_tool_call.log
tool-history.jsonl — 최근 도구 호출 기록
Desktop Commander는 get_recent_tool_calls가 쓰는 JSON Lines 기록도 남깁니다. 기록마다 시각, 도구 이름, 인자, 걸린 시간, 돌려준 결과가 들어 있습니다. 이 기록은 시작할 때 디스크에서 불러오므로 MCP 서버를 다시 켜도 최근 기록이 남습니다.
기록이 커지지 않게 이렇게 관리합니다.
- 메모리에는 가장 최근 호출 1,000개까지만 둡니다.
- 저장하는 출력은 기록마다 4 KiB까지이고, 더 큰 출력은 생략 표시로 바뀝니다.
- 디스크 파일이 5 MiB를 넘으면 잘라서 가장 새로운 4 MiB 정도만 남깁니다.
- 시작할 때 기록이 2,000개를 넘으면 가장 최근 1,000개로 다시 씁니다.
get_recent_tool_calls와track_ui_event는 이 JSONL 기록에서 빠집니다.
위치:
- macOS/Linux:
~/.claude-server-commander/tool-history.jsonl - Windows:
%USERPROFILE%\.claude-server-commander\tool-history.jsonl
원격 호출과 서버 쪽 보관
Remote Desktop Commander로 실행한 호출도 로컬 MCP 서버가 처리하므로 위의 로컬 기록 파일을 똑같이 씁니다. Remote Desktop Commander 서비스는 호출을 전달하고 끝내기 위해 도구 인자와 결과를 mcp_remote_calls에 잠시 저장합니다. 터미널 기록은 끝난 직후 자동으로 정리되므로(1분 뒤부터 지울 수 있고, 만든 시각 기준 한 시간이 지나면 반드시 지움) 오래 남는 서버 쪽 감사 기록이 아닙니다.
이 로컬 기록 파일은 Desktop Commander의 선택 사항인 텔레메트리와도 별개입니다. 파일 자체가 텔레메트리로 올라가지는 않습니다. 텔레메트리는 「데이터 수집과 개인정보」와 PRIVACY.md를 보세요.
오래 걸리는 명령 다루기
시간이 걸릴 수 있는 명령은 이렇게 다룹니다.
execute_command는 제한 시간이 되면 처음까지의 출력과 함께 돌아옵니다- 명령은 백그라운드에서 계속 실행됩니다
- PID로
read_output을 써서 새 출력을 가져옵니다 - 멈추려면
force_terminate를 씁니다
설정 관리
⚠️ 중요한 보안 경고
포괄적인 보안 정보와 취약점 제보: SECURITY.md를 보세요
-
알려진 보안 한계: 디렉터리 제한과 명령 차단은 심볼릭 링크, 명령 치환, 절대 경로, 코드 실행 같은 여러 방법으로 우회할 수 있습니다
-
설정은 실제로 작업하는 채팅과 다른 채팅 창에서 바꾸세요. Claude가 파일 시스템 접근이 막히면
allowedDirectories같은 설정을 바꾸려고 시도할 때가 있습니다. -
allowedDirectories설정은 파일 시스템 작업만 제한합니다. 터미널 명령은 허용된 디렉터리 밖의 파일에도 접근할 수 있습니다. -
운영 환경의 보안을 위해서는 호스트 시스템과 완전히 격리해 주는 Docker 설치를 쓰세요.
설정 도구
제공되는 도구로 서버 설정을 관리할 수 있습니다.
// 설정 전체 가져오기
get_config({})
// 특정 설정 값 바꾸기
set_config_value({ "key": "defaultShell", "value": "/bin/zsh" })
// 여러 설정은 호출을 나눠서 바꾸기
set_config_value({ "key": "defaultShell", "value": "/bin/bash" })
set_config_value({ "key": "allowedDirectories", "value": ["/Users/username/projects"] })
설정은 서버 작업 디렉터리의 config.json에 저장되고 서버를 다시 켜도 유지됩니다.
fileWriteLineLimit 이해하기
fileWriteLineLimit 설정은 write_file 한 번에 쓸 수 있는 줄 수를 정합니다(기본 50줄). 이 제한에는 중요한 이유가 있습니다.
제한이 있는 이유:
- AI는 토큰을 낭비하기 쉽습니다: 파일에서 작은 수정 두 번을 하는 대신 AI가 파일 전체를 다시 쓰기로 할 때가 있습니다. 작은 변경으로 나눠 하게 하면 시간과 토큰이 줄어듭니다
- Claude UX 메시지 제한: 메시지 하나에 한도가 있고 「Continue」를 눌러도 잘 이어지지 않습니다. AI가 더 작은 덩어리로 일하게 하면 한도에 닿아도 여러 덩어리가 이미 끝나 있어서 작업이 사라지지 않고 마지막 덩어리부터 다시 시작하면 됩니다
제한 정하기:
// 원하면 수천으로 올려도 됩니다
set_config_value({ "key": "fileWriteLineLimit", "value": 1000 })
// 작게 두면 더 효율적으로 일하게 만듭니다
set_config_value({ "key": "fileWriteLineLimit", "value": 25 })
최댓값: 수천까지 올려도 됩니다 - 기술적인 제한은 없습니다.
권장 사용법:
- 토큰 낭비를 피하고 효율적으로 일하게 하려면 기본값(50)을 유지하세요
- 제한을 넘으면 시스템이 자동으로 나눠 쓰라고 제안합니다
- 덩어리가 작을수록 Claude가 메시지 한도에 닿았을 때 잃는 작업이 적습니다
모범 사례
-
설정을 바꾸는 전용 채팅을 만드세요: 설정 변경은 한 채팅에서 모두 하고, 실제 작업은 새 채팅에서 시작하세요.
-
빈
allowedDirectories에 주의하세요: 빈 배열([])로 두면 파일 작업에서 전체 파일 시스템 접근을 허용하는 것입니다. -
구체적인 경로를 쓰세요:
/처럼 넓은 경로 대신 접근할 디렉터리를 정확히 지정하세요. -
바꾼 뒤에는 항상 확인하세요:
get_config({})로 설정이 제대로 적용되었는지 확인하세요.
명령줄 옵션
Desktop Commander는 동작을 바꾸는 여러 명령줄 옵션을 지원합니다.
온보딩 끄기
기본적으로 Desktop Commander는 새 사용자(도구 호출이 10회 미만)에게 도움이 되는 온보딩 안내를 보여 줍니다. 이 동작은 끌 수 있습니다.
# 이번 세션에서만 온보딩 끄기
node dist/index.js --no-onboarding
# npm 스크립트를 쓰는 경우
npm run start:no-onboarding
# npx 설치는 claude_desktop_config.json을 고치세요:
{
"mcpServers": {
"desktop-commander": {
"command": "npx",
"args": [
"-y",
"@wonderwhy-er/desktop-commander@latest",
"--no-onboarding"
]
}
}
}
온보딩이 자동으로 꺼지는 경우:
- MCP 클라이언트 이름이 「desktop-commander」일 때
--no-onboarding플래그를 쓸 때- 사용자가 온보딩 안내를 썼거나 도구를 10회 넘게 호출한 뒤
디버그 정보:
온보딩이 꺼지면 서버가 "Onboarding disabled via --no-onboarding flag"를 기록합니다.
다른 셸 쓰기
명령 실행에 쓸 셸을 정할 수 있습니다.
// 기본 셸 쓰기(bash 또는 시스템 기본값)
execute_command({ "command": "echo $SHELL" })
// zsh 지정
execute_command({ "command": "echo $SHELL", "shell": "/bin/zsh" })
// bash 지정
execute_command({ "command": "echo $SHELL", "shell": "/bin/bash" })
셸 고유의 기능을 쓰거나 환경을 일관되게 유지할 수 있습니다.
디버깅
서버를 디버깅해야 한다면 디버그 모드로 설치할 수 있습니다.
# npx 사용
npx @wonderwhy-er/desktop-commander@latest setup --debug
# 로컬에 설치한 경우
npm run setup:debug
이렇게 하면 다음이 적용됩니다.
- Claude가 별도의 「desktop-commander」 서버를 쓰도록 설정합니다
--inspect-brk=9229플래그로 Node.js 인스펙터 프로토콜을 켭니다- 디버거가 연결될 때까지 시작 지점에서 실행을 멈춥니다
- 추가 디버깅 환경 변수를 켭니다
디버거를 연결하려면:
- Chrome에서
chrome://inspect에 들어가 Node.js 인스턴스를 찾으세요 - VS Code에서는 「Attach to Node Process」 디버그 구성을 쓰세요
- 다른 IDE나 도구에도 Node.js용 비슷한 「attach」 옵션이 있습니다
디버깅할 때 중요한 점:
--inspect-brk플래그 때문에 디버거가 연결될 때까지 서버가 시작할 때 멈춥니다- 디버깅 중에 아무 동작이 없다면 올바른 Node.js 프로세스에 연결했는지 확인하세요
- Node 프로세스가 여러 개 돌고 있을 수 있으니 9229 포트의 프로세스에 연결하세요
문제 해결:
- Claude가 디버그 서버를 쓰다 시간 초과가 나면 디버거가 제대로 연결되지 않았을 수 있습니다
- 제대로 연결되면 첫 중단점에서 멈춘 뒤 프로세스가 계속 실행됩니다
- 연결된 뒤에는 IDE에서 중단점을 더 추가할 수 있습니다
Model Context Protocol 연동
이 프로젝트는 MCP Filesystem Server를 확장해 다음을 제공합니다.
- Claude Desktop의 로컬 서버 지원
- 전체 시스템 명령 실행
- 프로세스 관리
- 파일 작업
- 검색/바꾸기 블록으로 코드 편집
Claude MCP를 살펴보는 과정에서 만들었습니다: https://youtube.com/live/TlbjFDbl5Us
Desktop Commander 후원
Desktop Commander MCP는 무료 오픈소스이지만 계속 나아가려면 후원이 필요합니다. 방침은 단순합니다. 잘되지 않으면 돈을 내지 않아도 됩니다. 하지만 Desktop Commander가 성공에 보탬이 되었다면 이 프로젝트의 성공에도 보태 주세요.
후원 방법: GitHub Sponsors(정기 후원) · Buy Me A Coffee(일회성) · Patreon(월 후원) · GitHub에서 별 누르기.
후원은 활발한 개발과 유지 보수, 새 기능과 연동 추가, 플랫폼 호환성 개선, 문서와 예제 개선, 더 단단한 커뮤니티를 만드는 데 쓰입니다.
웹사이트
최신 소식, 문서, 업데이트는 공식 웹사이트 https://desktopcommander.app/ 에서 보세요.
미디어
- 글: 「Claude with MCPs replaced Cursor & Windsurf. How did that happen?」 — Model Context Protocol을 쓰는 Claude가 개발자의 작업 방식을 어떻게 바꾸는지 설명합니다
- 영상: Claude Desktop Commander 영상 튜토리얼 — 설정하고 쓰는 방법
- 기사: AnalyticsIndiaMag 「This Developer Ditched Windsurf, Cursor Using Claude with MCPs」
- 커뮤니티: Discord 서버에서 도움을 받고 의견을 나누세요: https://discord.com/invite/kQ27sNnZr7
더 알아보기
원문 README에는 위에서 다룬 내용 말고도 다음 절이 있습니다. 자세한 내용은 저장소에서 확인하세요.
- 사용 후기 — YouTube 튜토리얼 영상에 달린 사용자 후기 모음
- 진행 중인 작업과 할 일 — 로드맵 성격의 목록
- 자주 묻는 질문 — FAQ.md
- 기여하기 — 기여 방법 안내
- 개인정보 — 선택 사항인 텔레메트리와 수집 데이터는 PRIVACY.md
- 보안 — SECURITY.md
라이선스
MIT 라이선스입니다. LICENSE를 보세요.