MCP용 터미널 컨트롤러

표준화된 인터페이스를 통해 안전한 터미널 명령 실행, 디렉토리 탐색 및 파일 시스템 작업을 가능하게 하는 MCP(모델 컨텍스트 프로토콜) 서버입니다.

특징

• 명령 실행 : 시간 초과 제어 및 포괄적인 출력 캡처를 통해 터미널 명령 실행
• 디렉토리 관리 : 직관적인 서식으로 디렉토리 콘텐츠를 탐색하고 나열합니다.
• 보안 조치 : 위험한 명령 및 작업에 대한 내장형 보호 장치
• 명령 기록 : 최근 명령 실행을 추적하고 표시합니다.
• 크로스 플랫폼 지원 : Windows 및 UNIX 기반 시스템 모두에서 작동합니다.
• 파일 작업 : 행 수준 정밀도로 파일 내용을 읽고, 쓰고, 업데이트하고, 삽입하고, 삭제합니다.

설치

Smithery를 통해 설치

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

지엑스피1

필수 조건

• 파이썬 3.11+
• MCP 호환 클라이언트(예: Claude Desktop)
• UV/UVX 설치됨(선택 사항, UVX 방식의 경우)

방법 1: PyPI 설치(권장)

PyPI에서 직접 패키지를 설치하세요:

또는 UV를 사용하는 것을 선호하는 경우:

방법 2: 소스에서

소스에서 설치를 선호하는 경우:

1. 이 저장소를 복제하세요:
   git clone https://github.com/GongRzhe/terminal-controller-mcp.git cd terminal-controller-mcp
2. 설치 스크립트를 실행합니다.
   python setup_mcp.py

클라이언트 구성

클로드 데스크탑

Claude Desktop에서 Terminal Controller를 사용하도록 구성하는 방법은 두 가지가 있습니다.

옵션 1: UVX 사용(권장)

Claude Desktop 구성 파일에 다음을 추가하세요.

옵션 2: Python 직접 사용

구성 경로는 운영 체제에 따라 다릅니다.

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• 윈도우 : %APPDATA%\Claude\claude_desktop_config.json

커서

커서의 경우 Claude Desktop과 비슷한 구성 설정을 사용합니다.

다른 MCP 클라이언트

다른 클라이언트의 경우 외부 MCP 서버를 구성하는 방법에 대한 설명서를 참조하세요.

용법

구성이 완료되면 MCP 클라이언트를 통해 자연어를 사용하여 터미널과 상호 작용할 수 있습니다.

• "현재 디렉토리에서 ls -la 명령을 실행하세요"
• "내 문서 폴더로 이동"
• "내 다운로드 디렉토리의 내용을 보여주세요"
• "최근 명령 내역을 보여주세요"
• "config.json의 내용을 읽어보세요"
• "script.py 파일의 5번째 줄을 'print("Hello World")'로 업데이트하세요."
• "로그 파일에서 10-15번째 줄을 삭제하세요"
• "텍스트 파일의 시작 부분에 새 줄을 삽입합니다"

API 참조

터미널 컨트롤러는 다음과 같은 MCP 도구를 제공합니다.

execute_command

터미널 명령을 실행하고 결과를 반환합니다.

매개변수:

• command : 실행할 명령줄 명령
• timeout : 명령 시간 초과(초) (기본값: 30)

보고:

• stdout, stderr 및 실행 상태를 포함한 명령 실행 출력

get_command_history

최근 명령 실행 기록을 가져옵니다.

매개변수:

• count : 반환할 최근 명령 수(기본값: 10)

보고:

• 포맷된 명령 기록 레코드

get_current_directory

현재 작업 디렉토리를 가져옵니다.

보고:

• 현재 작업 디렉토리의 경로

change_directory

현재 작업 디렉토리를 변경합니다.

매개변수:

• path : 전환할 디렉토리 경로

보고:

• 작업 결과 정보

list_directory

지정된 디렉토리에 있는 파일과 하위 디렉토리를 나열합니다.

매개변수:

• path : 내용을 나열할 디렉토리 경로(기본값: 현재 디렉토리)

보고:

• 디렉토리 및 파일 아이콘으로 포맷된 디렉토리 내용 목록

write_file

덮어쓰기 또는 추가 옵션을 사용하여 파일에 내용을 씁니다.

매개변수:

• path : 파일 경로
• content : 쓸 내용
• mode : 쓰기 모드('덮어쓰기' 또는 '추가', 기본값: '덮어쓰기')

보고:

• 쓰기 성공 여부 검증을 포함한 작업 결과 정보

read_file

선택적으로 행을 선택하여 파일에서 콘텐츠를 읽습니다.

매개변수:

• path : 파일 경로
• start_row : 읽을 시작 행(0부터 시작, 선택 사항)
• end_row : 읽을 마지막 행(0부터 시작, 포함, 선택 사항)

보고:

• 파일 내용 또는 선택한 줄

insert_file_content

파일의 특정 행에 내용을 삽입합니다.

매개변수:

• path : 파일 경로
• content : 삽입할 내용
• row : 삽입할 행 번호(0부터 시작, 선택 사항)
• rows : 삽입할 행 번호 목록(0부터 시작, 선택 사항)

보고:

• 작업 결과 정보

delete_file_content

파일의 특정 행의 내용을 삭제합니다.

매개변수:

• path : 파일 경로
• row : 삭제할 행 번호(0부터 시작, 선택 사항)
• rows : 삭제할 행 번호 목록(0부터 시작, 선택 사항)

보고:

• 작업 결과 정보

update_file_content

파일의 특정 행의 내용을 업데이트합니다.

매개변수:

• path : 파일 경로
• content : 지정된 행에 배치할 새 콘텐츠
• row : 업데이트할 행 번호(0부터 시작, 선택 사항)
• rows : 업데이트할 행 번호 목록(0부터 시작, 선택 사항)

보고:

• 작업 결과 정보

보안 고려 사항

터미널 관리자는 여러 가지 보안 조치를 구현합니다.

• 장시간 실행되는 명령을 방지하기 위한 시간 초과 제어
• 위험한 명령어 블랙리스트(rm -rf /, format, mkfs)
• 적절한 오류 처리 및 명령 실행 격리
• 특별히 허가된 명령 및 디렉토리에만 액세스

제한 사항

• 시간 초과 기간 내에 완료된 명령만 결과를 반환합니다.
• 기본적으로 서버는 서버를 실행하는 사용자와 동일한 파일 시스템 권한에 액세스할 수 있습니다.
• 터미널 인터페이스의 비대화적 특성으로 인해 일부 대화형 명령이 예상대로 작동하지 않을 수 있습니다.

문제 해결

문제가 발생하는 경우:

1. Python 버전이 3.11 이상인지 확인하세요.
2. Claude Desktop 구성이 올바른지 확인하세요
3. 오류를 확인하려면 터미널 컨트롤러를 직접 실행해보세요.
   python -m terminal_controller
4. UVX 관련 문제의 경우 다음을 시도해 보세요.
   uvx terminal_controller
5. 연결 오류가 있는지 MCP 클라이언트의 로그를 검토하세요.

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

특허

MIT