local-only server

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

Integrations

Allows execution of whitelisted shell commands with comprehensive security features including command and flag whitelisting, path validation, and protection against injection attacks.

CLI MCP 서버

포괄적인 보안 기능을 갖춘 제어된 명령줄 작업을 실행하기 위한 안전한 MCP(Model Context Protocol) 서버 구현입니다.

🔒 엄격한 검증을 통한 안전한 명령 실행
⚙️ '모두' 옵션을 사용하여 구성 가능한 명령 및 플래그 허용 목록
🛡️ 경로 탐색 방지 및 검증
🚫 쉘 오퍼레이터 주입 보호
⏱️ 실행 시간 초과 및 길이 제한
📝 자세한 오류 보고
🔄 비동기 작업 지원
🎯 작업 디렉토리 제한 및 유효성 검사

구성

환경 변수를 사용하여 서버를 구성합니다.

변하기 쉬운	설명	기본
`ALLOWED_DIR`	명령 실행을 위한 기본 디렉토리(필수)	없음 (필수)
`ALLOWED_COMMANDS`	허용된 명령의 쉼표로 구분된 목록 또는 '모두'	`ls,cat,pwd`
`ALLOWED_FLAGS`	허용된 플래그의 쉼표로 구분된 목록 또는 '모두'	`-l,-a,--help`
`MAX_COMMAND_LENGTH`	최대 명령 문자열 길이	`1024`
`COMMAND_TIMEOUT`	명령 실행 시간 초과(초)	`30`
`ALLOW_SHELL_OPERATORS`	쉘 연산자 허용(&&,

참고: ALLOWED_COMMANDS 또는 ALLOWED_FLAGS 'all'로 설정하면 각각 모든 명령이나 플래그가 허용됩니다.

설치

Smithery 를 통해 Claude Desktop용 CLI MCP 서버를 자동으로 설치하려면:

지엑스피1

사용 가능한 도구

실행 명령

허용된 디렉토리 내에서 허용된 CLI 명령을 실행합니다.

입력 스키마:

{
  "command": {
    "type": "string",
    "description": "Single command to execute (e.g., 'ls -l' or 'cat file.txt')"
  }
}

보안 참고 사항:

셸 연산자(&&, |, >, >>)는 기본적으로 지원되지 않지만 ALLOW_SHELL_OPERATORS=true 로 활성화할 수 있습니다.
ALLOWED_COMMANDS='all'이 아닌 이상 명령은 허용 목록에 추가되어야 합니다.
ALLOWED_FLAGS='all'이 아닌 이상 플래그는 허용 목록에 추가되어야 합니다.
모든 경로는 ALLOWED_DIR 내에 있는지 검증됩니다.

보안 규칙 표시

다음을 포함하여 현재 보안 구성 및 제한 사항을 표시합니다.

작업 디렉토리
허용된 명령
허용된 플래그
보안 제한(최대 명령 길이 및 시간 초과)

Claude Desktop과 함께 사용

~/Library/Application\ Support/Claude/claude_desktop_config.json 에 다음을 추가합니다.

개발/미공개 서버 구성

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "<path/to/the/repo>/cli-mcp-server",
        "run",
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

게시된 서버 구성

{
  "mcpServers": {
    "cli-mcp-server": {
      "command": "uvx",
      "args": [
        "cli-mcp-server"
      ],
      "env": {
        "ALLOWED_DIR": "</your/desired/dir>",
        "ALLOWED_COMMANDS": "ls,cat,pwd,echo",
        "ALLOWED_FLAGS": "-l,-a,--help,--version",
        "MAX_COMMAND_LENGTH": "1024",
        "COMMAND_TIMEOUT": "30",
        "ALLOW_SHELL_OPERATORS": "false"
      }
    }
  }
}

작동하지 않거나 UI에 표시되지 않는 경우 uv clean 사용하여 캐시를 지우세요.

보안 기능

✅ '모두' 옵션을 사용하여 허용 목록 시행 명령
✅ '모두' 옵션을 사용하여 플래그 검증
✅ 경로 탐색 방지 및 정규화
✅ 셸 운영자 차단( ALLOW_SHELL_OPERATORS=true 통한 옵트인 지원 포함)
✅ 명령 길이 제한
✅ 실행 시간 초과
✅ 작업 디렉토리 제한 사항
✅ 심볼릭 링크 확인 및 검증

오류 처리

서버는 다음에 대한 자세한 오류 메시지를 제공합니다.

보안 위반(CommandSecurityError)
명령 시간 초과(CommandTimeoutError)
잘못된 명령 형식
경로 보안 위반
실행 실패(CommandExecutionError)
일반 명령 오류(CommandError)

개발

필수 조건

파이썬 3.10+
MCP 프로토콜 라이브러리

건축 및 출판

배포를 위해 패키지를 준비하려면:

종속성 동기화 및 잠금 파일 업데이트:
uv sync
패키지 배포 빌드:
uv build
이렇게 하면 dist/ 디렉토리에 소스와 휠 배포판이 생성됩니다.
PyPI에 게시:
uv publish --token {{YOUR_PYPI_API_TOKEN}}

디버깅

MCP 서버는 stdio를 통해 실행되므로 디버깅이 어려울 수 있습니다. 최상의 디버깅 환경을 위해서는 MCP Inspector 사용을 강력히 권장합니다.

다음 명령을 사용하여 npm 통해 MCP Inspector를 시작할 수 있습니다.

npx @modelcontextprotocol/inspector uv --directory {{your source code local directory}}/cli-mcp-server run cli-mcp-server

Inspector를 실행하면 브라우저에서 접근하여 디버깅을 시작할 수 있는 URL이 표시됩니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

더 많은 정보나 지원이 필요하면 프로젝트 저장소에서 이슈를 열어주세요.

You must be authenticated.

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

Tools

안전한 실행과 사용자 정의 가능한 보안 정책을 갖춘 명령줄 인터페이스

Table of Contents

cli-mcp-server