슈퍼쉘 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

수동 설치

# Clone the repository
git clone https://github.com/cfdude/super-shell-mcp.git
cd super-shell-mcp

# Install dependencies
npm install

# Build the project
npm run build

용법

서버 시작

npm start

또는 직접:

node build/index.js

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 코드 구성

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "super-shell-mcp"
  ],
  "alwaysAllow": [],
  "disabled": false
}

NPX를 사용한 Claude Desktop 구성

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "super-shell-mcp"
  ],
  "alwaysAllow": false,
  "disabled": false
}

옵션 2: 로컬 설치 사용

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

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js"
  ],
  "alwaysAllow": [],
  "disabled": false
}

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

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js",
    "--shell=/usr/bin/bash"
  ],
  "alwaysAllow": [],
  "disabled": false
}

Windows 11 예제

"super-shell": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npx-cli.js",
        "-y",
        "super-shell-mcp",
        "C:\\Users\\username"
      ],
      "alwaysAllow": [],
      "disabled": false
    }

클로드 데스크톱 구성

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

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js"
  ],
  "alwaysAllow": false,
  "disabled": false
}

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

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

"super-shell": {
  "command": "node",
  "args": [
    "/path/to/super-shell-mcp/build/index.js",
    "--shell=C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
  ],
  "alwaysAllow": false,
  "disabled": false
}

/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`

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

{
  "command": "ls",
  "args": ["-la"]
}

`get_whitelist`

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

{}

`add_to_whitelist`

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

{
  "command": "python3",
  "securityLevel": "safe",
  "description": "Run Python 3 scripts"
}

`update_security_level`

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

{
  "command": "python3",
  "securityLevel": "requires_approval"
}

`remove_from_whitelist`

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

{
  "command": "python3"
}

`get_pending_commands`

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

{}

`approve_command`

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

{
  "commandId": "command-uuid-here"
}

`deny_command`

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

{
  "commandId": "command-uuid-here",
  "reason": "This command is potentially dangerous"
}

기본적으로 허용된 명령

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

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

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 도구를 사용하여 허용 목록을 확장할 수 있습니다. 예:

{
  "command": "npm",
  "securityLevel": "requires_approval",
  "description": "Node.js package manager"
}

NPM 패키지 정보

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

NPX 사용의 이점

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

수동 설정 없음 : 저장소 복제, 종속성 설치 또는 프로젝트 빌드가 필요하지 않습니다.
자동 업데이트 : 항상 최신 게시 버전을 사용합니다.
크로스 플랫폼 호환성 : Windows, macOS 및 Linux에서 동일한 방식으로 작동합니다.
단순화된 구성 : 절대 경로가 없는 더 짧은 구성
유지 관리 감소 : 관리하거나 업데이트할 로컬 파일이 없습니다.

GitHub에서 사용

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

"super-shell": {
  "command": "npx",
  "args": [
    "-y",
    "github:cfdude/super-shell-mcp"
  ],
  "alwaysAllow": [],  // For Roo Code
  "disabled": false
}

자신의 버전 게시하기

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

package.json을 귀하의 세부 정보로 업데이트하세요.
"bin" 필드가 올바르게 구성되었는지 확인하세요.
"bin": { "super-shell-mcp": "./build/index.js" }
npm에 게시:
npm publish

NPX 모범 사례

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

실행 파일 진입점 : 메인 파일에는 shebang 라인( #!/usr/bin/env node )이 포함되어 있으며 빌드하는 동안 실행 가능하게 됩니다.
패키지 구성 :
- "type": "module" - ES 모듈이 사용되도록 보장합니다.
- "bin" 필드 - 명령 이름을 진입점에 매핑합니다.
- "files" 필드 - 게시할 때 포함할 파일을 지정합니다.
- "prepare" 스크립트 - 설치 시 컴파일이 수행되도록 보장합니다.
TypeScript 구성 :
- "module": "NodeNext" - 적절한 ES 모듈 지원
- "moduleResolution": "NodeNext" - ES 모듈과 일치
자동 설치 및 실행 :
- MCP 클라이언트 구성은 npx -y 사용하여 패키지를 자동으로 설치하고 실행합니다.
- 프로세스가 백그라운드에서 실행되므로 터미널 창이 닫히지 않습니다.
출판 과정 :
# Update version in package.json npm version patch # or minor/major as appropriate # Build and publish npm publish

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

문제 해결

크로스 플랫폼 문제

Windows 관련 문제

PowerShell 스크립트 실행 정책
- 문제 : PowerShell이 "이 시스템에서는 스크립트 실행이 비활성화되어 있습니다" 오류로 인해 스크립트 실행을 차단할 수 있습니다.
- 해결 방법 : PowerShell을 관리자 권한으로 실행하고 Set-ExecutionPolicy RemoteSigned 실행하거나 셸을 구성할 때 -ExecutionPolicy Bypass 매개변수를 사용합니다.
경로 구분 기호
- 문제 : Windows는 경로에 백슬래시( \ )를 사용하는데, JSON에서는 이를 이스케이프해야 합니다.
- 해결 방법 : JSON 구성 파일에서 이중 백슬래시( \\ )를 사용합니다(예: C:\\Windows\\System32\\cmd.exe
명령을 찾을 수 없습니다
- 문제 : Windows에는 ls , grep 등의 Unix 명령어가 없습니다.
- 해결 방법 : Windows와 동일한 명령( ls 대신 dir , grep 대신 findstr )을 사용하세요.

macOS/Linux 관련 문제

셸 권한
- 문제 : 명령 실행 시 권한이 거부됨
- 해결 방법 : chmod +x /path/to/shell 사용하여 셸에 적절한 권한이 있는지 확인하세요.
환경 변수
- 문제 : MCP 서버에서 환경 변수를 사용할 수 없음
- 해결 방법 : 셸의 프로필 파일( .zshrc , .bashrc 등)에 환경 변수를 설정합니다.

일반적인 문제 해결

셸 감지 문제
- 문제 : 서버가 올바른 셸을 감지하지 못함
- 해결 방법 : 구성에서 셸 경로를 명시적으로 지정하세요.
명령 실행 시간 초과
- 문제 : 명령 실행 시간이 너무 길어지고 시간 초과가 발생합니다.
- 해결 방법 : 명령 서비스 생성자에서 시간 초과 값을 늘리세요

로깅 시스템

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

로그 파일 위치
- 기본값: 서버 디렉토리의 logs/super-shell-mcp.log
- 로그 디렉토리는 Git(.gitkeep 파일)에 의해 자동으로 생성되고 추적됩니다.
- 로그 파일 자체는 .gitignore를 통해 Git에서 제외됩니다.
- 서버 작업, 명령 실행 및 승인 워크플로에 대한 자세한 정보가 포함되어 있습니다.
로그 수준
- INFO : 일반 운영 정보
- DEBUG : 자세한 디버깅 정보
- ERROR : 오류 조건 및 예외
로그 보기
- 로그를 확인하려면 표준 파일 보기 명령을 사용하세요.
  # View the entire log cat logs/super-shell-mcp.log # Follow log updates in real-time tail -f logs/super-shell-mcp.log
로그 내용
- 서버 시작 및 구성
- 명령 실행 요청 및 결과
- 승인 워크플로 이벤트(보류, 승인, 거부)
- 오류 조건 및 문제 해결 정보
화이트리스트 관리
- 문제 : 허용 목록에 사용자 지정 명령을 추가해야 함
- 해결 방법 : add_to_whitelist 도구를 사용하여 사용자 환경에 맞는 명령을 추가하세요.

특허

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

Integrations