MCP 터미널 서버

Windows 서비스로 실행할 수 있고 셸 명령을 실행하고 출력을 스트리밍하는 엔드포인트를 노출하는 가벼운 FastAPI 서버입니다.

특징

Windows 서비스 또는 디버그 모드로 실행
셸 명령을 실행하고 실시간으로 출력을 스트리밍합니다.
API 키 인증
속도 제한
환경 변수 또는 구성 파일을 통해 구성 가능
강력한 오류 처리 및 로깅
실패 시 자동 프로세스 재시작

설치

필수 조건

윈도우 운영체제
Python 3.7 이상
관리자 권한(서비스 설치용)

설치 단계

이 저장소를 복제하거나 소스 코드를 다운로드하세요
관리자 권한으로 PowerShell을 엽니다.
프로젝트 디렉토리로 이동합니다
설치 스크립트를 실행합니다.

지엑스피1

이렇게 하면:

필요한 Python 종속성 설치
임의의 API 키를 생성하세요(또는 귀하가 제공한 키를 사용하세요)
구성 파일을 만듭니다
Windows 서비스를 설치하고 시작합니다.

설치 옵션

다음 매개변수를 사용하여 설치를 사용자 정의할 수 있습니다.

.\install_service.ps1 -ApiKey "your-api-key" -Port 8080 -Host "127.0.0.1" -LogLevel "debug"

사용 가능한 매개변수:

-ApiKey : 인증을 위한 사용자 정의 API 키
-Port : 서버의 포트 번호 (기본값: 8000)
-Host : 바인딩할 호스트 주소(기본값: 0.0.0.0)
-LogLevel : 로그 레벨(디버그, 정보, 경고, 오류, 중요)
-ConfigFile : 사용자 정의 구성 파일의 경로

구성

서버는 다음을 통해 구성할 수 있습니다.

환경 변수
구성 파일(config.json)
설치 중 명령줄 인수

구성 파일

샘플 구성 파일( config.json.sample )이 제공됩니다. 이 파일을 config.json 파일에 복사하여 수정할 수 있습니다.

{
    "host": "0.0.0.0",
    "port": 8000,
    "log_level": "info",
    "log_file": "mcp_terminal_server.log",
    "max_log_size_mb": 10,
    "log_backup_count": 5,
    "restart_on_failure": true,
    "max_restart_attempts": 5,
    "restart_delay_seconds": 10,
    "shutdown_timeout_seconds": 30,
    "working_directory": null
}

환경 변수

환경 변수를 사용하여 서버를 구성할 수도 있습니다.

MCP_TERMINAL_API_KEY : 인증을 위한 API 키
MCP_HOST : 바인딩할 호스트 주소
MCP_PORT : 서버의 포트 번호
MCP_LOG_LEVEL : 로그 레벨
MCP_LOG_FILE : 로그 파일 경로
MCP_MAX_LOG_SIZE_MB : 최대 로그 파일 크기(MB)
MCP_LOG_BACKUP_COUNT : 보관할 로그 백업 파일 수
MCP_RESTART_ON_FAILURE : 실패 시 서버를 다시 시작할지 여부
MCP_MAX_RESTART_ATTEMPTS : 재시작 시도의 최대 횟수
MCP_RESTART_DELAY_SECONDS : 재시작 시도 사이의 지연 시간
MCP_SHUTDOWN_TIMEOUT_SECONDS : 정상적인 종료를 위한 시간 초과
MCP_WORKING_DIRECTORY : 서버의 작업 디렉토리

서비스 관리

서비스 명령

다음 명령을 사용하여 서비스를 관리할 수 있습니다.

# Install the service
python service.py install

# Start the service
python service.py start

# Stop the service
python service.py stop

# Restart the service
python service.py restart

# Remove the service
python service.py remove

# Update the service configuration
python service.py update

# Run in debug mode (not as a service)
python service.py debug

로그

로그는 구성된 로그 파일(기본값: mcp_terminal_server.log )에 저장됩니다. 로그에는 다음이 포함됩니다.

서비스 시작/중지 이벤트
명령 실행
오류 및 경고
건강 검진 결과

API 사용

테스트 클라이언트

다음 기능을 갖춘 서버와 상호 작용할 수 있는 강력한 테스트 클라이언트가 제공됩니다.

더 나은 사용성을 위한 명령줄 인수
API 키 인증 지원
가독성 향상을 위한 컬러 출력
출력을 파일에 저장하기 위한 지원
강력한 오류 처리 및 로깅
명령 기록이 있는 대화형 모드
서버 상태 점검 기능

기본 사용법

# Run a command
python test_client.py -c "dir" -k "your-api-key"

# Check server health
python test_client.py --health

# Interactive mode
python test_client.py -k "your-api-key"

# Save output to a file
python test_client.py -c "systeminfo" --save-output output.txt

# Specify server URL
python test_client.py -s "http://example.com:8000" -c "dir"

# Enable verbose output
python test_client.py -v -c "dir"

# Show version
python test_client.py --version

구성 파일

테스트 클라이언트는 JSON 구성 파일을 사용하여 구성할 수 있습니다. 제공된 샘플을 기반으로 client_config.json 파일을 생성하세요.

{
    "server_url": "http://localhost:8000",
    "api_key": "your-api-key-here",
    "timeout": 60,
    "verbose": false
}

그런 다음 다음과 함께 사용하세요.

python test_client.py --config client_config.json

환경 변수

테스트 클라이언트는 환경 변수를 통한 구성도 지원합니다.

MCP_TERMINAL_API_KEY : 인증을 위한 API 키
MCP_TERMINAL_SERVER_URL : 서버 URL

API 엔드포인트

POST /run : 명령 실행
- X-API-Key 헤더에 API 키가 필요합니다.
- 요청 본문: {"command": "your command"}
- 명령 출력과 함께 스트리밍 응답을 반환합니다.
GET /health : 서버 상태 확인
- {"status": "healthy", "active_sessions": 0} 반환합니다.

보안 고려 사항

프로덕션에서는 항상 기본 API 키를 변경하세요
서버에 로컬로만 접근 가능해야 하는 경우 호스트를 127.0.0.1 로 제한합니다.
프로덕션에서 HTTPS 사용을 고려하세요
서버는 잠재적으로 위험한 명령을 차단하지만 추가 보안 조치가 필요할 수 있습니다.

문제 해결

로그 파일에서 오류를 확인하세요
콘솔 출력을 보려면 디버그 모드에서 실행하세요: python service.py debug
서비스가 실행 중인지 확인하세요: Get-Service -Name "MCP_Terminal_Server"
서비스 관련 오류에 대한 Windows 이벤트 뷰어를 확인하세요.

특허

MIT

MCP Terminal Server

Integrations