Ubuntu MCP Server

KR: Ubuntu OS의 패키지 및 서비스 관리를 MCP(Model Context Protocol) 도구로 제공하는 서버입니다. EN: This server exposes Ubuntu OS package and service management as MCP (Model Context Protocol) tools.

KR: 로컬 호스트 또는 SSH 연동을 통해 apt 패키지 업데이트, systemctl 서비스 제어 및 시스템 버전 정보 확인을 자동화할 수 있습니다. EN: You can automate apt package updates, systemctl service control, and system version checks locally or via SSH integration.

1) 인코딩 / Encoding

• KR: 이 문서는 UTF-8 기준입니다.
• EN: This document is written in UTF-8.

2) 환경 변수 / Environment Variables

공통 옵션 / Common Options

• PORT (선택/Optional): HTTP 모드 사용 시 서버가 바인딩할 포트 (기본값: 3000)
• TRANSPORT (선택/Optional): 서버 통신 방식 (stdio 또는 http, 기본값: stdio)

원격 제어 (SSH) 옵션 / Remote Control (SSH) Options

KR: 아래 SSH 환경 변수를 하나라도 설정하면 원격 서버로 연결합니다. 설정하지 않으면 로컬 환경(child_process)에서 실행합니다. EN: If the SSH environment variables below are set, commands are executed on the remote server. Otherwise, they fall back to local execution.

• SSH_HOST (선택/Optional): 연결할 SSH 서버 주소 (IP 또는 도메인)

• SSH_PORT (선택/Optional): SSH 포트 (기본값: 22)

• SSH_USER (선택/Optional): SSH 연결에 사용할 사용자명

• SSH_PASSWORD (선택/Optional): SSH 비밀번호 (비밀번호 인증 시 사용)

• SSH_PRIVATE_KEY (선택/Optional): SSH 개인 키 경로 또는 내용 (키 인증 시 사용)

• KR: 대부분의 명령어 실행 시 충분한 권한(루트 또는 sudo 패스워드 불필요 상태)이 시스템에 구성되어 있어야 합니다.

• EN: Sufficient privileges (root or passwordless sudo) must be configured on the system for most commands to run.

3) 실행 / Run

npm install
npm run build
npm start

4) MCP 서버 설정 / MCP Server Configuration

npx 설정 / npx Configuration

{
  "mcpServers": {
    "ubuntu-remote": {
      "command": "npx",
      "args": ["-y", "mcp-ubuntu"],
      "env": {
        "SSH_HOST": "192.168.1.10",
        "SSH_PORT": "22",
        "SSH_USER": "root",
        "SSH_PASSWORD": "your_password"
      }
    }
  }
}

5) 도구 분류 / Tool Categories

A. 패키지 관리 / Package Management

1. ubuntu_apt_update

• KR: 패키지 목록 인덱스 갱신 (apt-get update)
• EN: Update package list index (apt-get update).
• 인자 / Args: 없음 / None

2. ubuntu_apt_upgrade

• KR: 패키지 업그레이드 수행 (apt-get upgrade -y)
• EN: Perform package upgrades (apt-get upgrade -y).
• 인자 / Args: 없음 / None

B. 서비스 관리 / Service Management

1. ubuntu_service_manage

• KR: 시스템 서비스 상태 제어 (systemctl start/stop/restart)
• EN: Control system service status (systemctl start/stop/restart).
• 인자 / Args: service_name (required), action (required: start, stop, restart)

C. 시스템 정보 / System Information

1. ubuntu_get_system_info

• KR: Ubuntu OS 버전 및 커널 정보 조회 (lsb_release, uname)
• EN: Fetch Ubuntu OS version and kernel info (lsb_release, uname).
• 인자 / Args: 없음 / None