개요
Desktop Commander MCP는 Claude 등 AI 어시스턴트에게 터미널 제어, 파일 검색 및 코드 편집 기능을 제공합니다. 명령 실행, 프로세스 관리, 파일 읽기/쓰기 및 텍스트 치환을 지원합니다. MCP Filesystem Server를 기반으로 구축되었으며, 대화형 프로세스 제어 및 파일 미리보기 기능이 추가되었습니다.
README 미리보기
# Desktop Commander MCP\n### Search, update, manage files and run terminal commands with AI\n\n[](https://www.npmjs.com/package/@wonderwhy-er/desktop-commander)\n[](https://agentaudit.dev/skills/desktop-commander)\n[](https://archestra.ai/mcp-catalog/wonderwhy-er__desktopcommandermcp)\n[](https://smithery.ai/server/@wonderwhy-er/desktop-commander)\n[](https://www.buymeacoffee.com/wonderwhyer)\n\n\n[](https://discord.gg/kQ27sNnZr7)\n\n\nWork with code and text, run processes, and automate tasks, going far beyond other AI editors - while using host client subscriptions instead of API token costs.\n\n\n \n\n\n## 🖥️ Try the Desktop Commander App (Beta)\n\n**Want a better experience?** The Desktop Commander App gives you everything the MCP server does, plus:\n\n- **Use any AI model** — Claude, GPT-4.5, Gemini 2.5, or any model you prefer\n- **See file changes live** — visual file previews as AI edits your files\n- **Add custom MCPs and context** — extend with your own tools, no config files\n- **Coming soon** — skills system, dictation, background scheduled tasks, and more\n\n**👉 [Download the App](https://desktopcommander.app/#download)** (macOS & Windows)\n\n> The MCP server below still works great with Claude Desktop and other MCP clients — the app is for those who want a dedicated, polished experience.\n\n## Table of Contents\n- [Features](#features)\n- [How to install](#how-to-install)\n- [Getting Started](#getting-started)\n- [Usage](#usage)\n- [File Preview UI & Markdown Editor](#file-preview-ui--markdown-editor)\n- [Handling Long-Running Commands](#handling-long-running-commands)\n- [Work in Progress and TODOs](#roadmap)\n- [Sponsors and Supporters](#support-desktop-commander)\n- [Website](#website)\n- [Media](#media)\n- [Testimonials](#testimonials)\n- [Frequently Asked Questions](#frequently-asked-questions)\n- [Contributing](#contributing)\n- [License](#license)\n\nAll of your AI development tools in one place.\nDesktop Commander puts all dev tools in one c
FAQ (5)
문제 해결read_multiple_files가 여러 개의 큰 이미지를 반환할 때 발생하는 'MCP error -32000: Connection closed' 오류는 어떻게 해결하나요?
**Remote Desktop Commander를 0.2.51 이상으로 업그레이드하세요**. 버전 0.2.51은 크기가 큰 read_multiple_files 응답이 MCP stdio 버퍼를 초과하지 않도록 보호하며, 로컬 Desktop Commander 자식 프로세스가 종료되면 진행 중인 호출을 즉시 실패 처리합니다.
근본 원인: @modelcontextprotocol/sdk 1.30.0에서 StdioClientTransport는 기본 **10 MiB 읽기 버퍼**를 사용하며, 단일 메시지가 이를 초과하면 전송을 닫습니다. Base64로 인코딩된 이미지 여러 개는 이 제한을 쉽게 초과할 수 있습니다. 예를 들어, 약 8.8 MB의 원본 이미지가 JSON 오버헤드 전에 약 11.8 MB의 Base64를 생성했습니다.
0.2.47에 대한 해결 방법:
1. PNG/JPEG 파일을 개별적으로 또는 더 작은 배치로 읽으세요.
2. 결합된 Base64 페이로드를 10 MiB 미만으로 유지하세요. Base64 및 JSON 오버헤드를 고려하여 원본 이미지는 요청당 보수적으로 **7 MB 이하**로 유지하세요.
3. 클라이언트가 Not connected를 보고하면 Remote Desktop Commander를 다시 시작하세요.
4. read_multiple_files 호출당 더 적은 수의 파일로 다시 시도하세요.
문제 해결WebSocket 소켓 1006 이후 "IncreaseConnectionPool"와 함께 Desktop Commander 원격이 오프라인으로 전환되는 문제를 해결하는 방법
원격 에이전트를 Desktop Commander 0.2.51 이상으로 업그레이드하세요. 재연결/커넥션 풀 문제가 해당 릴리스에서 수정되어 확인되었습니다. 기존 원격 에이전트를 모두 중지하고, 중복된 index.js remote/Node 프로세스를 제거한 다음, 다음 명령으로 다시 시작하세요:
npx @wonderwhy-er/desktop-commander@latest remote수정된 릴리스를 명시적으로 테스트하려면 다음을 사용하세요:
npx @wonderwhy-er/desktop-commander@0.2.51 remote0.2.47 버전에서는 에이전트를 재시작해도 연결이 일시적으로만 복구됩니다. 업그레이드 후에도 오류가 계속되면, 특히 Cloudflare 525 SSL 오류와 함께 발생하는 경우, 별도의 서비스 용량 또는 연결 문제일 수 있으므로 네트워크/SSL 경로와 Desktop Commander 서비스 상태를 확인하세요.
문제 해결Desktop Commander MCP 서버가 initialize 중에 브라우저 환영 페이지를 열지 못하게 하려면 어떻게 해야 하나요?
환영 페이지는 Desktop Commander의 첫 실행 온보딩이며 한 번만 열립니다. 온보딩 없이 실행하려면 다음을 실행하세요:
npx @wonderwhy-er/desktop-commander@latest setup --no-onboardingDesktop Commander를 시작할 때 --no-onboarding을 전달하거나, 설정에서 onboarding_injection: false로 지정할 수도 있습니다. 이렇게 하면 헤드리스, IDE 또는 CI 환경에서 MCP initialize 핸드셰이크 중에 브라우저 창과 utm_source 애널리틱스 요청이 트리거되지 않습니다.
문제 해결desktop-commander 0.2.52에서 `npm audit --omit=dev`가 보고한 높은 심각도의 취약점을 어떻게 수정하나요?
해당 취약점은 병합된 프로덕션 의존성 업데이트를 통해 수정되었으며, 이 업데이트는 npm audit --omit=dev 탐지 결과를 38건에서 0건으로 줄입니다. 이 수정 사항이 포함된 릴리스가 게시되면 해당 릴리스로 업그레이드하세요:
npm install -g @wonderwhy-er/desktop-commander@latestMCP 클라이언트 구성을 통해 실행하는 경우 다음을 사용하세요:
["-y", "@wonderwhy-er/desktop-commander@latest"]그런 다음 MCP 서버를 재시작하고 다음 명령으로 확인하세요:
node --version
npm audit --omit=devNode.js **22.12 이상**이 필요합니다. 업그레이드하기 전까지는 무제한 시스템 액세스 권한이 부여되지 않도록 ChatGPT/MCP 구성에서 desktop-commander를 비활성화하거나 제거하세요.
문제 해결Windows에서 Desktop Commander read_file 이후 os.replace() 또는 fs.rename()이 'PermissionError: WinError 5'(ERROR_ACCESS_DENIED) 오류로 실패하는 이유는 무엇인가요?
원인: Desktop Commander의 read_file이 라인 한도에서 읽기가 조기 중단될 때마다 파일 핸들을 누수합니다. readFromStartWithReadline은 readline 루프를 빠져나와 rl.close()를 호출하지만, readline.Interface.close()는 기반이 되는 fs.createReadStream을 닫지 않으므로, 서버가 종료될 때까지 Node 프로세스가 파일을 열린 상태로 유지합니다. 그 결과 Windows는 다른 프로세스에서의 원자적 rename 기반 교체(os.replace(), fs.rename(), File.Move(...,true), MOVEFILE_REPLACE_EXISTING을 사용한 MoveFileEx)를 WinError 5 / EPERM으로 거부합니다.
발생 조건(0.2.46–0.2.52에서 확인, 0.3.0에서 재발): 누수는 EOF까지 읽지 않고 break에 도달할 때만 발생합니다. 예: 5줄짜리 파일을 length=5로 읽으면(또는 1200줄 파일에 기본 1000줄 제한을 적용하면) 핸들이 누수되지만, 같은 파일을 length=6으로 읽으면 누수되지 않습니다. Windows Restart Manager로 잠금 소유자를 확인할 수 있습니다(Desktop Commander의 node.exe를 찾아보세요).
해결 방법:
1. 기존 잠금 해제: Desktop Commander / Claude Desktop을 완전히 재시작합니다(정상 종료 시 누수된 모든 핸들이 해제되며, 이후 파일을 정상적으로 이동/교체할 수 있습니다).
2. 새로운 누수 발생 방지: read_file을 호출할 때 파일의 전체 줄 수보다 큰 length를 전달하여 스트림이 EOF까지 읽고 정상적으로 닫히도록 합니다. 기본 1000줄 제한 상태에서 큰 파일을 부분적으로 읽는 것은 피하세요.
3. 코드 수정(기여자용): 네 곳의 readline 호출 지점 모두에서 입력 ReadStream을 캡처하고, finally 블록에서 stream.destroy()를 호출한 뒤, 반환하기 전에 스트림의 close 이벤트를 await합니다. 또한 입력 스트림과 readline 인터페이스 양쪽 모두에서 error/abort 이벤트를 처리합니다.