Skip to main content
Glama
Sign In
enesjakozh

Claude Desktop Commander MCP

by wonderwhy-er
Verified
npmGitHub
TypeScript
MIT License
12,588
1,734
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

local-only server

The server can only run on the client’s local machine because it depends on local resources.

데스크톱 커맨더 MCP

AI를 사용하여 파일을 검색, 업데이트, 관리하고 터미널 명령을 실행합니다.

간략하게 설명하자면, 핵심은 네 가지입니다. 터미널 명령어, diff 기반 파일 편집, ripgrep 기반 폴더 텍스트 검색, URL에서 파일 읽기 기능입니다.

목차

이 서버는 Claude 데스크톱 앱이 컴퓨터에서 장기 실행 터미널 명령을 실행하고 MCP(Model Context Protocol)를 통해 프로세스를 관리할 수 있도록 해줍니다. + MCP 파일 시스템 서버를 기반으로 구축되어 추가 검색 및 파일 편집 기능을 제공합니다.

특징

  • 출력 스트리밍으로 터미널 명령 실행
  • 명령 시간 초과 및 백그라운드 실행 지원
  • 프로세스 관리(프로세스 나열 및 종료)
  • 장기 실행 명령에 대한 세션 관리
  • 서버 구성 관리:
    • 구성 값 가져오기/설정
    • 여러 설정을 한 번에 업데이트
    • 서버를 다시 시작하지 않고도 동적 구성 변경
  • 전체 파일 시스템 작업:
    • 파일 읽기/쓰기
    • 디렉토리 생성/나열
    • 파일/디렉토리 이동
    • 파일 검색
    • 파일 메타데이터 가져오기
    • 코드 편집 기능:
    • 작은 변경 사항에 대한 수술 텍스트 교체
    • 주요 변경 사항에 대한 전체 파일 다시 작성
    • 다중 파일 지원
    • 패턴 기반 교체
    • vscode-ripgrep 기반 재귀 코드 또는 폴더 내 텍스트 검색

설치

먼저, Claude Desktop 앱을 다운로드하여 설치했고 npm도 설치 했는지 확인하세요.

옵션 1: npx를 통해 설치

터미널에서 이것을 실행하세요

지엑스피1

디버깅 모드(Node.js 검사기 연결 허용):

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

실행 중이면 Claude를 다시 시작하세요.

옵션 2: bash 스크립트 설치 프로그램 사용(macOS)

macOS 사용자의 경우 자동화된 bash 설치 프로그램을 사용하면 Node.js 버전을 확인하고 필요한 경우 설치하고 Desktop Commander를 자동으로 구성할 수 있습니다.

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

이 스크립트는 원활한 설정 환경을 위해 모든 종속성과 구성을 자동으로 처리합니다.

옵션 3: Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Desktop Commander를 자동으로 설치하려면:

npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude

옵션 4: claude_desktop_config에 직접 추가

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" ] } } }

실행 중이면 Claude를 다시 시작하세요.

옵션 5: 현지에서 결제

  1. 복제 및 빌드:
git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git cd DesktopCommanderMCP npm run setup

실행 중이면 Claude를 다시 시작하세요.

설치 명령은 다음을 수행합니다.

  • 종속성 설치
  • 서버를 빌드하세요
  • Claude의 데스크톱 앱 구성
  • 필요한 경우 Claude의 구성에 MCP 서버를 추가합니다.

Desktop Commander 업데이트

npx(옵션 1) 또는 Smithery(옵션 2)를 통해 설치한 경우, Claude를 재시작할 때마다 Desktop Commander가 최신 버전으로 자동 업데이트됩니다. 수동 업데이트 과정은 필요하지 않습니다.

수동 설치의 경우, setup 명령을 다시 실행하여 업데이트할 수 있습니다.

용법

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

사용 가능한 도구

범주도구설명
구성get_configJSON으로 전체 서버 구성을 가져옵니다(blockedCommands, defaultShell, allowedDirectories 포함)
set_config_value키로 특정 구성 값을 설정합니다. 사용 가능한 설정은 다음과 같습니다. • blockedCommands : 실행할 수 없는 셸 명령 배열 • defaultShell : 명령에 사용할 셸(예: bash, zsh, powershell) • allowedDirectories : 서버가 파일 작업을 위해 액세스할 수 있는 파일 시스템 경로 배열 (⚠️ 터미널 명령은 이러한 디렉터리 외부의 파일에도 액세스할 수 있습니다)
단말기execute_command구성 가능한 시간 초과 및 셸 선택으로 터미널 명령 실행
read_output실행 중인 터미널 세션에서 새 출력을 읽습니다.
force_terminate실행 중인 터미널 세션을 강제로 종료합니다.
list_sessions모든 활성 터미널 세션 나열
list_processes자세한 정보와 함께 실행 중인 모든 프로세스를 나열합니다.
kill_processPID로 실행 중인 프로세스 종료
파일 시스템read_file로컬 파일 시스템이나 URL에서 콘텐츠를 읽습니다(텍스트와 이미지 지원)
read_multiple_files여러 파일을 동시에 읽기
write_file파일 내용을 완전히 교체합니다(대규모 변경에 가장 적합)
create_directory새 디렉토리를 생성하거나 디렉토리가 존재하는지 확인하세요.
list_directory파일 및 디렉토리의 자세한 목록을 얻으세요
move_file파일 및 디렉토리 이동 또는 이름 변경
search_files대소문자 구분 없이 문자열 일치를 사용하여 이름으로 파일 찾기
search_coderipgrep을 사용하여 파일 내용 내의 텍스트/코드 패턴 검색
get_file_info파일이나 디렉토리에 대한 자세한 메타데이터 검색
텍스트 편집edit_block수술 텍스트 교체 적용(파일 크기의 20% 미만 변경에 가장 적합)

도구 사용 예

검색/바꾸기 블록 형식:

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

예:

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

URL 지원

  • read_file 이제 로컬 파일과 URL 모두에서 콘텐츠를 가져올 수 있습니다.
  • 예: 웹 리소스에서 읽기 위해 isUrl: true 매개변수를 사용한 read_file
  • 원격 소스의 텍스트와 이미지 콘텐츠를 모두 처리합니다.
  • 이미지(로컬 또는 URL)는 Claude의 인터페이스에 텍스트가 아닌 시각적으로 표시됩니다.
  • Claude는 실제 이미지 콘텐츠를 보고 분석할 수 있습니다.
  • URL 요청에 대한 기본 30초 시간 초과

장기 실행 명령 처리

시간이 걸릴 수 있는 명령의 경우:

구성 관리

⚠️ 중요 보안 경고

  1. 실제 작업을 진행하는 곳과는 별도의 채팅 창에서 구성을 변경하세요 . Claude는 작업 중 파일 시스템 접근 제한에 직면하면 구성 설정(예: allowedDirectories )을 수정하려고 할 수 있습니다.
  2. allowedDirectories 설정은 현재 파일 시스템 작업만 제한하며 , 터미널 명령은 제한하지 않습니다. 터미널 명령은 허용된 디렉터리 외부의 파일에도 계속 액세스할 수 있습니다. 완전한 터미널 샌드박싱은 로드맵에 있습니다.

구성 도구

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

// 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 에 저장되며 서버를 다시 시작해도 유지됩니다.

모범 사례

  1. 구성 변경을 위한 전용 채팅 만들기 : 모든 구성 변경을 하나의 채팅에서 완료한 다음, 실제 작업을 위한 새 채팅을 시작합니다.
  2. allowedDirectories 비어 있는 상태로 두는 것에 주의하세요 . 이를 빈 배열( [] )로 설정하면 파일 작업을 위해 전체 파일 시스템에 액세스할 수 있습니다.
  3. 구체적인 경로 사용 : / 와 같은 광범위한 경로를 사용하는 대신 액세스하려는 정확한 디렉토리를 지정하세요.
  4. 변경 후에는 항상 구성을 확인하세요 . get_config({}) 사용하여 변경 사항이 올바르게 적용되었는지 확인하세요.

다양한 껍질 사용하기

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

// 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. PID와 함께 read_output 사용하여 새 출력을 얻습니다.
  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 검사기 프로토콜을 활성화합니다.
  3. 디버거가 연결될 때까지 시작 시 실행을 일시 중지합니다.
  4. 추가 디버깅 환경 변수 활성화

디버거를 연결하려면:

  • Chrome에서 chrome://inspect 방문하여 Node.js 인스턴스를 찾으세요.
  • VS Code에서 "노드 프로세스에 연결" 디버그 구성을 사용하세요.
  • 다른 IDE/도구에는 Node.js 디버깅을 위한 유사한 "첨부" 옵션이 있을 수 있습니다.

중요한 디버깅 참고 사항:

  • 디버거가 연결될 때까지 서버는 시작 시 일시 중지됩니다( --inspect-brk 플래그로 인해).
  • 디버깅 중에 활동이 보이지 않으면 올바른 Node.js 프로세스에 연결되어 있는지 확인하세요.
  • 여러 노드 프로세스가 실행 중일 수 있습니다. 포트 9229에 있는 프로세스에 연결하세요.
  • 디버그 서버는 Claude의 MCP 서버 목록에서 "desktop-commander-debug"로 식별됩니다.

문제 해결:

  • Claude가 디버그 서버를 사용하려고 시도하는 동안 시간이 초과되면 디버거가 제대로 연결되지 않았을 수 있습니다.
  • 제대로 연결되면 프로세스는 첫 번째 중단점에 도달한 후에도 실행을 계속합니다.
  • 연결되면 IDE에 추가 중단점을 추가할 수 있습니다.

모델 컨텍스트 프로토콜 통합

이 프로젝트는 MCP 파일 시스템 서버를 확장하여 다음을 지원합니다.

  • Claude Desktop의 로컬 서버 지원
  • 전체 시스템 명령 실행
  • 프로세스 관리
  • 파일 작업
  • 검색/바꾸기 블록을 사용한 코드 편집

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

완료

  • 2025-04-16 더 나은 구성 - 허용된 경로, 명령 및 셸 환경에 대한 설정이 개선되었습니다.
  • 2025-04-14 Windows 환경 수정 - Windows 플랫폼에 특정된 문제 해결
  • 2025-04-14 Linux 개선 사항 - 다양한 Linux 배포판과의 호환성 향상
  • 2025년 12월 4일 허용 디렉터리 및 차단된 명령 개선 - 파일 읽기/쓰기 및 터미널 명령 제한에 대한 보안 및 경로 검증이 개선되었습니다. 터미널은 허용된 디렉터리를 무시하고 파일에 계속 액세스할 수 있습니다.
  • 2025년 11월 4일 셸 구성 - 명령 실행을 위한 기본 셸을 구성하는 기능 추가
  • 07-04-2025 URL 지원 추가 - read_file 명령이 이제 URL에서 콘텐츠를 가져올 수 있습니다.
  • 2025-03-28 "Watching /" JSON 오류 수정 - JSON이 아닌 메시지를 처리하고 서버 충돌을 방지하기 위해 사용자 지정 stdio 전송을 구현했습니다.
  • 2025-03-25 더 나은 코드 검색 ( 병합 ) - 컨텍스트 인식 결과를 통한 향상된 코드 탐색

진행 중인 작업 및 TODO

현재 다음과 같은 기능이 탐색 중입니다.

  • WSL 지원 - Linux 통합을 위한 Windows 하위 시스템
  • SSH 지원 - 원격 서버 명령 실행
  • csv/pdf와 같은 더 나은 파일 지원
  • 보안 강화를 위한 Mac/Linux/Windows용 터미널 샌드박싱
  • 파일 읽기 모드 - 예를 들어 HTML을 일반 텍스트 또는 마크다운으로 읽을 수 있습니다.

웹사이트

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

메디아

다음 리소스를 통해 이 프로젝트에 대해 자세히 알아보세요.

기사

MCP를 탑재한 Claude가 Cursor와 Windsurf를 대체했습니다. 어떻게 이런 일이 가능했을까요? - 모델 컨텍스트 프로토콜 기능을 탑재한 Claude가 개발자 워크플로우를 어떻게 변화시키고 있는지 자세히 살펴봅니다.

동영상

Claude Desktop Commander 비디오 튜토리얼 - Commander를 효과적으로 설정하고 사용하는 방법을 시청하세요.

AnalyticsIndiaMag에 게재됨

이 개발자는 MCP와 함께 Claude를 사용하여 Windsurf와 Cursor를 포기했습니다.

지역 사회

도움을 받고, 피드백을 공유하고, 다른 사용자와 소통하려면 Discord 서버 에 가입하세요.

추천사

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyyBt6_ShdDX_rIOad4AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgztdHvDMqTb9jiqnf54AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=UgyQFTmYLJ4VBwIlmql4AaABAg

https://www.youtube.com/watch?v=ly3bed99Dy8&lc=Ugy4-exy166_Ma7TH-h4AaABAg

https://medium.com/@pharmx/you-sir-are-my-hero-62cff5836a3e

기여하다

이 프로젝트가 유용하다고 생각되시면 GitHub에서 ⭐ 별점을 주세요! 다른 사람들이 이 프로젝트를 알아보고 더 발전하는 데 도움이 됩니다.

커뮤니티 여러분의 참여를 환영합니다! 버그를 발견하셨든, 기능 요청이 있으시든, 또는 코드 기여를 원하시든, 다음과 같은 방법으로 도움을 주실 수 있습니다.

  • 버그를 발견하셨나요? github.com/wonderwhy-er/DesktopCommanderMCP/issues 에서 이슈를 열어주세요.
  • 기능 아이디어가 있으신가요? 이슈 섹션에 기능 요청을 제출해 주세요.
  • 코드에 기여하고 싶으신가요? 저장소를 포크하고, 브랜치를 생성한 후 풀 리퀘스트를 제출하세요.
  • 질문이나 토론이 있으신가요? GitHub 토론 탭에서 토론을 시작하세요.

크고 작음에 관계없이 모든 기여를 환영합니다!

이 도구가 귀하의 업무 흐름에 유용하다고 생각되면 이 프로젝트를 지원해 주시기 바랍니다.

자주 묻는 질문

다음은 몇 가지 일반적인 질문에 대한 답변입니다. 더 자세한 FAQ는 자세한 FAQ 문서를 참조하세요.

DesktopCommanderMCP란 무엇인가요?

Claude Desktop이 파일 시스템과 터미널에 접속할 수 있도록 해주는 MCP 도구로, Claude를 코딩, 자동화, 코드베이스 탐색 등을 위한 다재다능한 도우미로 만들어줍니다.

이것은 커서/윈드서프와 어떻게 다릅니까?

IDE 중심 도구와 달리, Claude Desktop Commander는 코딩 환경뿐만 아니라 전체 OS에서 작동하는 솔루션 중심 접근 방식을 제공합니다. Claude는 파일을 분할하지 않고 전체를 읽고, 여러 프로젝트를 동시에 작업할 수 있으며, 지속적인 검토 없이 한 번에 변경 사항을 실행합니다.

API 크레딧을 구매해야 합니까?

아니요. 이 도구는 Claude Desktop의 표준 Pro 구독(월 20달러)과 호환되지만 API 호출과는 호환되지 않으므로 구독료 외에 추가 비용이 발생하지 않습니다.

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

네, npx 또는 Smithery를 통해 설치한 경우, Claude를 재시작하면 Desktop Commander가 최신 버전으로 자동 업데이트됩니다. 수동 업데이트 과정은 필요하지 않습니다.

가장 흔한 사용 사례는 무엇입니까?

  • 복잡한 코드베이스 탐색 및 이해
  • 다이어그램 및 문서 생성
  • 시스템 전반의 작업 자동화
  • 여러 프로젝트를 동시에 작업
  • 정밀한 제어로 수술 코드 변경

도구를 설치하거나 사용하는 데 문제가 있습니다. 어디서 도움을 받을 수 있나요?

커뮤니티 지원을 위해 Discord 서버 에 가입하고, 알려진 문제는 GitHub 이슈 에서 확인하거나, 문제 해결 팁을 위한 전체 FAQ를 검토하세요. 더욱 사용자 친화적인 환경을 위해 웹사이트 FAQ 섹션을 방문하실 수도 있습니다. 새로운 문제가 발생하면 문제에 대한 자세한 내용을 GitHub 이슈에 기재해 주세요.

데이터 수집

Desktop Commander는 설치 및 설정 과정에서 도구 개선을 위해 익명의 사용 데이터를 수집합니다. 여기에는 다음이 포함됩니다.

  • 운영 체제 정보
  • Node.js 및 NPM 버전
  • 설치 방법 및 쉘 환경
  • 오류 메시지(설정 중에 발생하는 경우)

이 데이터는 Google 애널리틱스 분석을 통해 수집되며, 기계에서 생성된 고유 ID와 연결됩니다. 개인정보는 수집되지 않습니다. 이는 도구 사용 방식을 이해하고 일반적인 문제를 파악하는 데 도움이 됩니다.

현재 이 데이터 수집에 대한 기본 제공 옵트아웃 옵션을 향후 출시 버전에 추가하기 위해 작업 중입니다. 현재 옵트아웃을 원하시면 방화벽 설정에서 google-analytics.com 으로의 네트워크 연결을 차단하실 수 있습니다.

특허

MIT

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

Tools

View all tools

MCP를 통해 Claude 데스크톱 앱에서 터미널 명령을 실행하고 컴퓨터의 파일을 편집할 수 있도록 합니다. 여기에는 명령 실행, 프로세스 관리, diff 기반 파일 편집 등의 기능이 포함됩니다.

  1. Search, update, manage files and run terminal commands with AI
    1. Table of Contents
      1. Features
        1. Installation
          1. Option 1: Install through npx
          2. Option 2: Using bash script installer (macOS)
          3. Option 3: Installing via Smithery
          4. Option 4: Add to claude_desktop_config by hand
          5. Option 5: Checkout locally
          6. Updating Desktop Commander
        2. Usage
          1. Available Tools
          2. Tool Usage Examples
          3. URL Support
        3. Handling Long-Running Commands
          1. Configuration Management
            1. ⚠️ Important Security Warnings
            2. Configuration Tools
            3. Best Practices
          2. Using Different Shells
            1. Debugging
              1. Model Context Protocol Integration
                1. DONE
                  1. Work in Progress and TODOs
                    1. Website
                      1. Media
                        1. Article
                        2. Video
                        3. Publication at AnalyticsIndiaMag
                        4. Community
                      2. Testimonials
                        1. Contributing
                          1. Frequently Asked Questions
                            1. What is DesktopCommanderMCP?
                            2. How is this different from Cursor/Windsurf?
                            3. Do I need to pay for API credits?
                            4. Does Desktop Commander automatically update?
                            5. What are the most common use cases?
                            6. I'm having trouble installing or using the tool. Where can I get help?
                          2. Data Collection
                            1. License

                              Related Resources

                              Appeared in Searches

                              ID: zempur9oh4