mcp-shell-sudo

Linux용 MCP 서버로, Python으로 작성되었으며 argv를 사용하여 로컬 명령을 실행합니다. PASSWORD_SUDO를 통해 비대화형 sudo를 지원하고, ALLOW_COMMANDS를 통해 선택적 명령 허용 목록을 제공하며, Bubblewrap을 사용하여 파일 시스템 쓰기를 WORK_DIR로 제한할 수 있습니다.

요구 사항

• Linux.

• Python 3.11+.

• uv 권장.

• MCP Python SDK 2.0.0.

• 권한 상승 명령을 실행할 경우 sudo.

• WORK_DIR를 구성할 경우 bubblewrap.

Debian/Ubuntu에서:

sudo apt update
sudo apt install -y bubblewrap

Related MCP server: MCP Process Server

환경 변수

PASSWORD_SUDO

MCP 서버를 실행하는 사용자의 비밀번호.

• 비어 있거나 설정되지 않음: 서버는 비밀번호를 임의로 만들거나 대화형으로 요청하지 않습니다. sudo로 시작하는 명령은 sudo -n을 사용하여 실행되며, 유효한 캐시된 자격 증명이 이미 존재하거나 NOPASSWD 규칙이 구성된 경우에만 작동합니다.

• 설정됨: sudo는 -S로 실행되며, 비밀번호는 stdin을 통해 제공됩니다. argv나 로그에는 절대 나타나지 않습니다.

예:

"PASSWORD_SUDO": "my-password"

지원되는 형식은 다음과 같습니다:

["sudo", "id"]

sudo -u postgres ...와 같은 사용자 지정 sudo 플래그는 허용되지 않습니다. 이는 정책 계층이 전체 sudo 명령 문법을 해석할 필요가 없도록 하기 위함입니다.

WORK_DIR

선택적 작업 디렉터리.

• 비어 있거나 설정되지 않음: MCP 서버는 도구 호출에 지정된 기존 디렉터리에서 작업할 수 있습니다.

• 설정됨: 서버는 엄격 모드로 전환됩니다. directory는 WORK_DIR 내부에 있어야 하며, 모든 프로세스는 /가 읽기 전용이고 WORK_DIR이 읽기-쓰기로 마운트되며 /tmp와 /run이 임시인 Bubblewrap 마운트 네임스페이스 내에서 실행됩니다.

cwd만 사용하는 것은 이 격리를 보장하기에 충분하지 않습니다. 프로세스는 여전히 /etc, /home/...에 쓰거나 프로젝트 외부의 심볼릭 링크를 따라갈 수 있습니다. 이러한 이유로 WORK_DIR이 구성되었지만 bwrap을 사용할 수 없는 경우 서버는 시작 시 실패합니다.

이 모드에서는 sudo가 거부됩니다. 호스트 수준의 권한 상승은 파일 시스템 쓰기가 작업 공간에만 국한된다는 보장과 호환되지 않기 때문입니다.

ALLOW_COMMANDS

쉼표로 구분된 실행 파일 이름 목록.

"ALLOW_COMMANDS": "git,ls,cat,grep,python,node,pnpm"

• 비어 있거나 설정되지 않음: 모든 실행 파일이 허용됩니다.

• 설정됨: 목록의 정확한 실행 파일 이름만 허용되며, /usr/bin/git과 같은 경로가 아닌 이름으로 호출되어야 합니다.

• 명령이 sudo로 시작하면 sudo 뒤의 실제 실행 파일이 검증됩니다.

허용 목록은 인수가 아닌 실행 파일에 적용됩니다. bash, python, node, env 또는 프로세스 실행이 가능한 다른 도구를 허용하면 MCP 클라이언트가 할 수 있는 작업이 크게 확장됩니다.

설치

uv sync

개발용:

uv sync --extra dev

수동 실행

uv run mcp-shell-sudo

전송 방식은 stdio입니다. JSON-RPC 메시지를 손상시키지 않기 위해 로그는 stdout에 절대 기록되지 않으며, 대신 stderr에 기록됩니다.

MCP 구성

제한 없는 명령과 sudo 활성화 예시:

{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/mcp-shell-sudo",
        "run",
        "mcp-shell-sudo"
      ],
      "env": {
        "PASSWORD_SUDO": "YOUR_PASSWORD",
        "WORK_DIR": "",
        "ALLOW_COMMANDS": ""
      }
    }
  }
}

특정 프로젝트로 제한된 예시:

{
  "mcpServers": {
    "shell-project": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/mcp-shell-sudo",
        "run",
        "mcp-shell-sudo"
      ],
      "env": {
        "PASSWORD_SUDO": "",
        "WORK_DIR": "/home/user/projects/app",
        "ALLOW_COMMANDS": "git,ls,cat,grep,find,python,node,pnpm"
      }
    }
  }
}

shell_execute 도구

기본 입력:

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

작업 디렉터리 사용:

{
  "command": ["git", "status"],
  "directory": "backend"
}

stdin 사용:

{
  "command": ["cat"],
  "stdin": "hello\n"
}

sudo 사용:

{
  "command": ["sudo", "id"]
}

응답:

{
  "stdout": "uid=0(root) gid=0(root) groups=0(root)\n",
  "stderr": "",
  "status": 0,
  "execution_time": 0.031,
  "timed_out": false,
  "output_limited": false
}

shell_config 도구

유효한 비밀 정보가 아닌 구성을 반환합니다.

PASSWORD_SUDO는 절대 반환하지 않으며, sudo 비밀번호가 구성되었는지 여부만 나타냅니다.

구현된 보안 조치

• create_subprocess_exec를 사용하며 shell=True를 사용하지 않습니다.

• command는 명시적 argv 배열로 전달됩니다.

• sudo 비밀번호는 argv, 응답, 로그 또는 자식 프로세스 환경에 절대 나타나지 않습니다.

• PASSWORD_SUDO가 구성되지 않은 경우 sudo -n은 대화형 비밀번호 프롬프트를 기다리며 프로세스가 멈추는 것을 방지합니다.

• ALLOW_COMMANDS는 단순 sudo 호출 뒤의 실제 실행 파일을 검증합니다.

• 고정되고 축소된 PATH를 사용하여 . 또는 임의의 상속된 경로에서 실행 파일을 확인하지 않도록 합니다.

• 전체 MCP 서버 환경을 상속하는 대신 축소된 자식 환경을 사용합니다.

• 호출별 타임아웃: 기본 60초, 최대 600초.

• 출력 제한: 스트림당 2MiB. 제한을 초과하면 전체 프로세스 그룹이 종료됩니다.

• 프로세스는 새 세션에서 실행되며, 타임아웃 시 전체 프로세스 그룹이 종료됩니다.

• WORK_DIR는 Bubblewrap을 사용하며 격리를 제공할 수 없으면 실패 시 닫힙니다(fail closed).

중요한 제한 사항

1. ALLOW_COMMANDS=""는 MCP 서버를 실행하는 사용자의 권한으로 임의의 명령 실행을 의미합니다. PASSWORD_SUDO도 구성된 경우 MCP 클라이언트는 루트로 작업을 요청할 수 있습니다. 이 구성은 제어하는 클라이언트와 모델에서만 사용하십시오.

2. 실행 파일 허용 목록은 명령 인수를 의미적으로 검증하지 않습니다. python, node, bash, sh, perl 및 유사한 도구는 사실상 임의 코드 실행을 허용하는 것과 동일합니다.

3. WORK_DIR는 쓰기 가능한 파일 시스템 위치를 제한하지만 VM이나 네트워크 샌드박스처럼 동작하도록 의도된 것은 아닙니다. 네트워크 접근 권한이 있는 명령은 유효한 자격 증명을 가진 원격 리소스를 여전히 수정할 수 있습니다.

4. MCP 클라이언트 구성에 저장된 PASSWORD_SUDO는 해당 파일에 저장된 비밀로 유지됩니다. chmod 600으로 파일 권한을 제한하고 버전 관리에 커밋하지 마십시오.

테스트

uv run --extra dev pytest
uv run --extra dev ruff check .