hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

Enables cloning the terminal-mcp-server repository to install and build the server
Enables command execution on Linux hosts, both locally and remotely via SSH
Supports using tmux for running long-running commands in persistent sessions on local or remote hosts

터미널 MCP 서버

터미널 MCP 서버는 로컬 또는 원격 호스트에서 명령을 실행할 수 있는 모델 컨텍스트 프로토콜(MCP) 서버입니다. AI 모델 및 기타 애플리케이션이 로컬 머신이나 SSH를 통해 원격 호스트에서 시스템 명령을 실행할 수 있도록 간단하면서도 강력한 인터페이스를 제공합니다.

특징

로컬 명령 실행 : 로컬 머신에서 직접 명령을 실행합니다.
원격 명령 실행 : SSH를 통해 원격 호스트에서 명령 실행
세션 지속성 : 지정된 시간(기본 20분) 동안 동일한 터미널 환경을 재사용하는 지속 세션 지원
환경 변수 : 명령에 대한 사용자 정의 환경 변수 설정
다양한 연결 방법 : stdio 또는 SSE(Server-Sent Events)를 통해 연결

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 terminal-mcp-server를 자동으로 설치하려면:

지엑스피1

수동 설치

# Clone the repository
git clone https://github.com/weidwonder/terminal-mcp-server.git
cd terminal-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

용법

서버 시작

# Start the server using stdio (default mode)
npm start

# Or run the built file directly
node build/index.js

SSE 모드에서 서버 시작

SSE(Server-Sent Events) 모드를 사용하면 HTTP를 통해 원격으로 서버에 연결할 수 있습니다.

# Start the server in SSE mode
npm run start:sse

# Or run the built file directly with SSE flag
node build/index.js --sse

다음 명령줄 옵션을 사용하여 SSE 서버를 사용자 정의할 수 있습니다.

옵션	설명	기본
`--port` 또는 `-p`	수신할 포트	8080
`--endpoint` 또는 `-e`	종료 지점 경로	/세
`--host` 또는 `-h`	바인딩할 호스트	로컬호스트

사용자 정의 옵션의 예:

# Start SSE server on port 3000, endpoint /mcp, and bind to all interfaces
node build/index.js --sse --port 3000 --endpoint /mcp --host 0.0.0.0

이렇게 하면 서버가 시작되고 http://0.0.0.0:3000/mcp 에서 SSE 연결을 수신합니다.

MCP Inspector로 테스트

# Start the MCP Inspector tool
npm run inspector

execute_command 도구

execute_command 도구는 Terminal MCP Server가 제공하는 핵심 기능으로, 로컬 또는 원격 호스트에서 명령을 실행하는 데 사용됩니다.

매개변수

매개변수	유형	필수의	설명
명령	끈	예	실행할 명령
주인	끈	아니요	연결할 원격 호스트입니다. 지정하지 않으면 명령이 로컬에서 실행됩니다.
사용자 이름	끈	호스트가 지정된 경우 필수	SSH 연결을 위한 사용자 이름
세션	끈	아니요	세션 이름(기본값은 "default"입니다. 동일한 세션 이름을 사용하면 20분 동안 동일한 터미널 환경이 재사용됩니다.)
환경	물체	아니요	환경 변수는 기본적으로 빈 객체로 설정됩니다.

예시

로컬에서 명령 실행

{
  "command": "ls -la",
  "session": "my-local-session",
  "env": {
    "NODE_ENV": "development"
  }
}

원격 호스트에서 명령 실행

{
  "host": "example.com",
  "username": "user",
  "command": "ls -la",
  "session": "my-remote-session",
  "env": {
    "NODE_ENV": "production"
  }
}

AI Assistant를 사용한 구성

Roo 코드로 구성

VSCode를 열고 Roo Code 확장 프로그램을 설치하세요.
Roo Code 설정 파일을 엽니다: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
다음 구성을 추가합니다.

stdio 모드(로컬 연결)의 경우

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

SSE 모드(원격 연결)의 경우

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

사용자 정의한 경우 localhost:8080/sse 실제 서버 주소, 포트 및 종단점으로 바꾸세요.

Cline으로 구성

Cline 설정 파일을 엽니다: ~/.cline/config.json
다음 구성을 추가합니다.

stdio 모드(로컬 연결)의 경우

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

SSE 모드(원격 연결)의 경우

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

Claude Desktop으로 구성

Claude Desktop 설정 파일을 엽니다: ~/Library/Application Support/Claude/claude_desktop_config.json
다음 구성을 추가합니다.

stdio 모드(로컬 연결)의 경우

{
  "mcpServers": {
    "terminal-mcp": {
      "command": "node",
      "args": ["/path/to/terminal-mcp-server/build/index.js"],
      "env": {}
    }
  }
}

SSE 모드(원격 연결)의 경우

{
  "mcpServers": {
    "terminal-mcp-sse": {
      "url": "http://localhost:8080/sse",
      "headers": {}
    }
  }
}

모범 사례

명령 실행

명령을 실행하기 전에 시스템 유형(Mac, Linux 등)을 확인하는 것이 가장 좋습니다.
경로 관련 문제를 방지하려면 전체 경로를 사용하세요.
환경을 유지해야 하는 명령 시퀀스의 경우 && 사용하여 여러 명령을 연결합니다.
장기 실행 명령의 경우 nohup 또는 screen / tmux 사용하는 것이 좋습니다.

SSH 연결

SSH 키 기반 인증이 설정되어 있는지 확인하세요.
연결이 실패하면 키 파일이 있는지 확인하세요(기본 경로: ~/.ssh/id_rsa )
원격 호스트에서 SSH 서비스가 실행 중인지 확인하세요.

세션 관리

관련 명령 간의 환경을 유지하려면 세션 매개변수를 사용하세요.
특정 환경이 필요한 작업의 경우 동일한 세션 이름을 사용하세요.
세션은 20분 동안 활동이 없으면 자동으로 종료됩니다.

오류 처리

명령 실행 결과에는 stdout과 stderr이 모두 포함됩니다.
명령이 성공적으로 실행되었는지 확인하려면 stderr을 확인하세요.
복잡한 작업의 경우 성공을 보장하기 위해 검증 단계를 추가하세요.

중요 참고 사항

원격 명령 실행을 위해서는 SSH 키 기반 인증을 미리 설정해야 합니다.
로컬 명령 실행의 경우 명령은 서버를 시작한 사용자의 컨텍스트에서 실행됩니다.
세션 시간 초과는 20분이며, 이 시간이 지나면 연결이 자동으로 종료됩니다.

This server cannot be installed

-

security - not tested

F

license - not found

-

quality - not tested

AI 모델이 SSH를 통해 로컬 머신이나 원격 호스트에서 시스템 명령을 실행할 수 있도록 하는 MCP 서버로, 영구 세션과 환경 변수를 지원합니다.

Appeared in Searches

A guide to BIM automation and tools