슈퍼쉘 MCP 서버

여러 플랫폼(Windows, macOS, Linux)에서 셸 명령을 실행하기 위한 MCP(Model Context Protocol) 서버입니다. 이 서버는 기본 제공 허용 목록 및 승인 메커니즘을 통해 셸 명령을 안전하게 실행할 수 있는 방법을 제공합니다.

특징

• Windows, macOS 및 Linux에서 MCP를 통해 셸 명령 실행

• 자동 플랫폼 감지 및 쉘 선택

• 여러 셸 지원:

  • Windows : cmd.exe, PowerShell

  • macOS : zsh, bash, sh

  • 리눅스 : bash, sh, zsh

• 보안 수준에 따른 명령 허용 목록:

  • 안전 : 승인 없이 실행할 수 있는 명령

  • 승인 필요 : 실행 전 명시적 승인이 필요한 명령

  • 금지됨 : 명시적으로 차단된 명령

• 플랫폼별 명령 허용 목록

• 잠재적으로 위험한 명령에 대한 비차단 승인 워크플로

• 파일 기반 로그를 갖춘 포괄적인 로깅 시스템

• 포괄적인 명령 관리 도구

• 진단을 위한 플랫폼 정보 도구

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Super Shell MCP Server를 자동으로 설치하려면:

지엑스피1

수동 설치

용법

서버 시작

또는 직접:

Roo Code 및 Claude Desktop에서 구성

Roo Code와 Claude Desktop은 모두 MCP 서버에 대해 유사한 구성 형식을 사용합니다. Super Shell MCP 서버를 설정하는 방법은 다음과 같습니다.

옵션 1: NPX 사용(권장)

Super Shell MCP를 사용하는 가장 쉬운 방법은 NPX를 사용하는 것입니다. NPX는 수동 설정 없이 npm에서 패키지를 자동으로 설치하고 실행합니다. 이 패키지는 NPM (https://www.npmjs.com/package/super-shell-mcp )에서 다운로드할 수 있습니다.

NPX를 사용한 Roo 코드 구성

NPX를 사용한 Claude Desktop 구성

옵션 2: 로컬 설치 사용

로컬 설치를 사용하려면 다음을 Roo Code MCP 설정 구성 파일( ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json 에 위치)에 추가하세요.

선택적으로 셸 매개변수를 추가하여 사용자 정의 셸을 지정할 수 있습니다.

Windows 11 예제

클로드 데스크톱 구성

~/Library/Application Support/Claude/claude_desktop_config.json 에 있는 Claude Desktop 구성 파일에 다음을 추가합니다.

Windows 사용자의 경우 구성 파일은 일반적으로 %APPDATA%\Claude\claude_desktop_config.json 에 있습니다.

플랫폼별 구성

윈도우

• 기본 셸: cmd.exe(또는 사용 가능한 경우 PowerShell)

• 구성 경로:

  • Roo 코드: %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json

  • 클로드 데스크톱: %APPDATA%\Claude\claude_desktop_config.json

• 셸 경로 예:

  • cmd.exe: C:\\Windows\\System32\\cmd.exe

  • PowerShell: C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe

  • PowerShell Core: C:\\Program Files\\PowerShell\\7\\pwsh.exe

맥OS

• 기본 셸: /bin/zsh

• 구성 경로:

  • Roo 코드: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

  • Claude 데스크톱: ~/Library/Application Support/Claude/claude_desktop_config.json

• 셸 경로 예:

  • zsh: /bin/zsh

  • 배시: /bin/bash

  • sh: /bin/sh

리눅스

• 기본 셸: /bin/bash(또는 $SHELL 환경 변수)

• 구성 경로:

  • Roo 코드: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

  • Claude 데스크톱: ~/.config/Claude/claude_desktop_config.json

• 셸 경로 예:

  • 배시: /bin/bash

  • sh: /bin/sh

  • zsh: /usr/bin/zsh

선택적으로 사용자 정의 셸을 지정할 수 있습니다.

/path/to/super-shell-mcp 저장소를 복제한 실제 경로로 바꾸세요.

메모 :

• Roo 코드의 경우: 보안상의 이유로 alwaysAllow 빈 배열 [] 로 설정하는 것이 좋습니다. 명령을 실행하기 전에 승인을 요청하기 때문입니다. 특정 명령을 승인 없이 허용하려면 배열에 해당 명령 이름을 추가할 수 있습니다. 예: "alwaysAllow": ["execute_command", "get_whitelist"] .

• Claude Desktop의 경우: 보안상의 이유로 alwaysAllow 를 false 로 설정하는 것이 좋습니다. Claude Desktop은 배열 대신 부울 값을 사용하는데, false 모든 명령에 승인이 필요함을 의미하고, true 모든 명령이 확인 없이 허용됨을 의미합니다.

중요 : alwaysAllow 매개변수는 Super Shell MCP 서버 자체가 아닌 MCP 클라이언트(Roo Code 또는 Claude Desktop)에서 처리됩니다. 클라이언트가 서버로 요청을 보내기 전에 승인 절차를 처리하므로 서버는 두 형식 중 어떤 형식이든 정상적으로 작동합니다.

사용 가능한 도구

서버는 다음과 같은 MCP 도구를 제공합니다.

get_platform_info

현재 플랫폼과 셸에 대한 정보를 얻습니다.

execute_command

현재 플랫폼에서 셸 명령을 실행합니다.

get_whitelist

허용된 명령 목록을 가져옵니다.

add_to_whitelist

허용 목록에 명령을 추가합니다.

update_security_level

허용 목록에 있는 명령의 보안 수준을 업데이트합니다.

remove_from_whitelist

허용 목록에서 명령을 제거합니다.

get_pending_commands

승인 대기 중인 명령 목록을 가져옵니다.

approve_command

보류 중인 명령을 승인합니다.

deny_command

보류 중인 명령을 거부합니다.

기본적으로 허용된 명령

서버에는 감지된 플랫폼을 기반으로 자동으로 선택되는 플랫폼별 명령 허용 목록이 포함되어 있습니다.

일반 안전 명령(모든 플랫폼)

• echo - 표준 출력에 텍스트 인쇄

Unix 계열의 안전한 명령어(macOS/Linux)

• ls - 디렉토리 내용 나열

• pwd - 작업 디렉토리 인쇄

• echo - 표준 출력에 텍스트 인쇄

• cat - 파일 연결 및 인쇄

• grep - 파일에서 패턴 검색

• find - 디렉토리 계층 구조에서 파일 찾기

• cd - 디렉토리 변경

• head - 파일의 첫 번째 부분 출력

• tail - 파일의 마지막 부분 출력

• wc - 줄 바꿈, 단어, 바이트 수를 출력합니다.

Windows 전용 안전 명령

• dir - 디렉토리 내용 나열

• type - 텍스트 파일의 내용을 표시합니다.

• findstr - 파일에서 문자열 검색

• where - 프로그램 찾기

• whoami - 현재 사용자 표시

• hostname - 컴퓨터 이름 표시

• ver - 운영 체제 버전 표시

승인이 필요한 명령

승인이 필요한 Windows 명령

• copy - 파일 복사

• move - 파일 이동

• mkdir - 디렉토리 생성

• rmdir - 디렉토리 제거

• rename - 파일 이름 바꾸기

• attrib - 파일 속성 변경

승인이 필요한 Unix 명령어

• mv - 파일 이동(이름 바꾸기)

• cp - 파일 및 디렉토리 복사

• mkdir - 디렉토리 생성

• touch - 파일 타임스탬프를 변경하거나 빈 파일을 만듭니다.

• chmod - 파일 모드 비트 변경

• chown - 파일 소유자 및 그룹 변경

금지된 명령

Windows 금지 명령

• del - 파일 삭제

• erase - 파일 삭제

• format - 디스크 포맷

• runas - 다른 사용자로 프로그램 실행

유닉스 금지 명령어

• rm - 파일 또는 디렉토리 제거

• sudo - 다른 사용자로 명령 실행

보안 고려 사항

• 모든 명령은 MCP 서버를 실행하는 사용자의 권한으로 실행됩니다.

• 승인이 필요한 명령은 명시적으로 승인될 때까지 대기열에 보관됩니다.

• 금지된 명령은 실행되지 않습니다.

• 서버는 쉘 주입을 방지하기 위해 exec 대신 Node.js의 execFile 사용합니다.

• 인수는 지정된 경우 허용된 패턴에 대해 검증됩니다.

화이트리스트 확장

add_to_whitelist 도구를 사용하여 허용 목록을 확장할 수 있습니다. 예:

NPM 패키지 정보

Super Shell MCP는 https://www.npmjs.com/package/super-shell-mcp 에서 npm 패키지로 제공됩니다.

NPX 사용의 이점

NPX 방법을 사용하면(구성 섹션의 옵션 1에 표시된 대로) 다음과 같은 여러 가지 이점이 있습니다.

1. 수동 설정 없음 : 저장소 복제, 종속성 설치 또는 프로젝트 빌드가 필요하지 않습니다.

2. 자동 업데이트 : 항상 최신 게시 버전을 사용합니다.

3. 크로스 플랫폼 호환성 : Windows, macOS 및 Linux에서 동일한 방식으로 작동합니다.

4. 단순화된 구성 : 절대 경로가 없는 더 짧은 구성

5. 유지 관리 감소 : 관리하거나 업데이트할 로컬 파일이 없습니다.

GitHub에서 사용

GitHub에서 최신 개발 버전을 직접 사용하려면:

자신의 버전 게시하기

npm에 수정된 버전을 게시하려면 다음을 수행하세요.

1. package.json을 귀하의 세부 정보로 업데이트하세요.

2. "bin" 필드가 올바르게 구성되었는지 확인하세요.

   "bin": { "super-shell-mcp": "./build/index.js" }

3. npm에 게시:

   npm publish

NPX 모범 사례

NPX를 사용하여 MCP 클라이언트와 최적의 통합을 위해 이 프로젝트는 다음과 같은 모범 사례를 따릅니다.

1. 실행 파일 진입점 : 메인 파일에는 shebang 라인( #!/usr/bin/env node )이 포함되어 있으며 빌드하는 동안 실행 가능하게 됩니다.

2. 패키지 구성 :

   • "type": "module" - ES 모듈이 사용되도록 보장합니다.

   • "bin" 필드 - 명령 이름을 진입점에 매핑합니다.

   • "files" 필드 - 게시할 때 포함할 파일을 지정합니다.

   • "prepare" 스크립트 - 설치 시 컴파일이 수행되도록 보장합니다.

3. TypeScript 구성 :

   • "module": "NodeNext" - 적절한 ES 모듈 지원

   • "moduleResolution": "NodeNext" - ES 모듈과 일치

4. 자동 설치 및 실행 :

   • MCP 클라이언트 구성은 npx -y 사용하여 패키지를 자동으로 설치하고 실행합니다.

   • 프로세스가 백그라운드에서 실행되므로 터미널 창이 닫히지 않습니다.

5. 출판 과정 :

   # Update version in package.json npm version patch # or minor/major as appropriate # Build and publish npm publish

이러한 방식을 사용하면 별도의 터미널 창이 없어도 MCP 클라이언트가 MCP 서버를 자동으로 시작할 수 있으므로 사용자 경험과 운영 효율성이 향상됩니다.

문제 해결

크로스 플랫폼 문제

Windows 관련 문제

1. PowerShell 스크립트 실행 정책

   • 문제 : PowerShell이 "이 시스템에서는 스크립트 실행이 비활성화되어 있습니다" 오류로 인해 스크립트 실행을 차단할 수 있습니다.

   • 해결 방법 : PowerShell을 관리자 권한으로 실행하고 Set-ExecutionPolicy RemoteSigned 실행하거나 셸을 구성할 때 -ExecutionPolicy Bypass 매개변수를 사용합니다.

2. 경로 구분 기호

   • 문제 : Windows는 경로에 백슬래시( \ )를 사용하는데, JSON에서는 이를 이스케이프해야 합니다.

   • 해결 방법 : JSON 구성 파일에서 이중 백슬래시( \\ )를 사용합니다(예: C:\\Windows\\System32\\cmd.exe

3. 명령을 찾을 수 없습니다

   • 문제 : Windows에는 ls , grep 등의 Unix 명령어가 없습니다.

   • 해결 방법 : Windows와 동일한 명령( ls 대신 dir , grep 대신 findstr )을 사용하세요.

macOS/Linux 관련 문제

1. 셸 권한

   • 문제 : 명령 실행 시 권한이 거부됨

   • 해결 방법 : chmod +x /path/to/shell 사용하여 셸에 적절한 권한이 있는지 확인하세요.

2. 환경 변수

   • 문제 : MCP 서버에서 환경 변수를 사용할 수 없음

   • 해결 방법 : 셸의 프로필 파일( .zshrc , .bashrc 등)에 환경 변수를 설정합니다.

일반적인 문제 해결

1. 셸 감지 문제

   • 문제 : 서버가 올바른 셸을 감지하지 못함

   • 해결 방법 : 구성에서 셸 경로를 명시적으로 지정하세요.

2. 명령 실행 시간 초과

   • 문제 : 명령 실행 시간이 너무 길어지고 시간 초과가 발생합니다.

   • 해결 방법 : 명령 서비스 생성자에서 시간 초과 값을 늘리세요

로깅 시스템

서버에는 디버깅과 모니터링을 더 쉽게 하기 위해 로그를 파일에 기록하는 포괄적인 로깅 시스템이 포함되어 있습니다.

1. 로그 파일 위치

   • 기본값: 서버 디렉토리의 logs/super-shell-mcp.log

   • 로그 디렉토리는 Git(.gitkeep 파일)에 의해 자동으로 생성되고 추적됩니다.

   • 로그 파일 자체는 .gitignore를 통해 Git에서 제외됩니다.

   • 서버 작업, 명령 실행 및 승인 워크플로에 대한 자세한 정보가 포함되어 있습니다.

2. 로그 수준

   • INFO : 일반 운영 정보

   • DEBUG : 자세한 디버깅 정보

   • ERROR : 오류 조건 및 예외

3. 로그 보기

   • 로그를 확인하려면 표준 파일 보기 명령을 사용하세요.

     # View the entire log cat logs/super-shell-mcp.log # Follow log updates in real-time tail -f logs/super-shell-mcp.log

4. 로그 내용

   • 서버 시작 및 구성

   • 명령 실행 요청 및 결과

   • 승인 워크플로 이벤트(보류, 승인, 거부)

   • 오류 조건 및 문제 해결 정보

5. 화이트리스트 관리

   • 문제 : 허용 목록에 사용자 지정 명령을 추가해야 함

   • 해결 방법 : add_to_whitelist 도구를 사용하여 사용자 환경에 맞는 명령을 추가하세요.

특허

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 약관에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.