Skip to main content
Glama
deenesjakoruzh
mkpvishnu

terminal-mcp

by mkpvishnu
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

문제점

모든 AI 코딩 도구는 동일한 벽에 부딪힙니다: 진짜 터미널에 접근할 수 없다는 것.

Claude Code의 Bash 도구, GitHub Copilot, Codex는 모두 격리된 서브프로세스에서 명령어를 실행합니다. 각 명령어는 새로 시작됩니다. 상태가 유지되지 않습니다. 즉:

  • SSH 세션 불가 - 원격 서버에 연결하여 여러 명령어를 실행할 수 없음

  • REPL 불가 - Python, Node, Ruby 인터프리터를 대화형으로 사용할 수 없음

  • 데이터베이스 CLI 불가 - psql, mysql, redis-cli 연결을 유지할 수 없음

  • TUI 앱 불가 - 화살표 키로 htop, vim, fzf를 탐색할 수 없음

  • 장기 실행 프로세스 불가 - 빌드 모니터링, 로그 감시, 개발 서버 실행 불가

Related MCP server: Interactive Terminal MCP Server

해결책

terminal-mcp는 AI 에이전트에게 진짜 터미널을 제공합니다. 도구 호출 간에도 유지되는 지속적인 PTY 세션. 명령어 전송, 출력 읽기, 키 입력, TUI 탐색 - 마치 사람이 터미널을 사용하는 것처럼.

uvx terminal-mcp

하나의 명령어. Claude Code, Claude Desktop, VS Code, Cursor, Windsurf에서 작동합니다.

빠른 시작

1. 설치 (30초)

# No install needed - run directly
uvx terminal-mcp

# Or install globally
pip install terminal-mcp

2. AI 클라이언트에 연결

~/.claude.json 또는 프로젝트 .mcp.json에 추가:

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

위의 원클릭 설치 배지를 클릭하거나 .vscode/mcp.json에 추가:

{
  "servers": {
    "terminal-mcp": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

~/.codeium/windsurf/mcp_config.json에 추가:

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

3. 확인

session_exec  exec="echo hello from terminal-mcp"

무엇을 할 수 있나요?

원격 서버에 SSH 접속

session_create   command="ssh user@prod-server.com"   label="prod"
session_interact session_id="a1b2c3d4"  input="df -h"  wait_for="\$"
session_interact session_id="a1b2c3d4"  input="docker ps"  wait_for="\$"
session_close    session_id="a1b2c3d4"

대화형 REPL 실행

session_create   command="python3"  label="python"
session_interact session_id="e5f6g7h8"  input="import pandas as pd"  wait_for=">>>"
session_interact session_id="e5f6g7h8"  input="df = pd.read_csv('data.csv')"  wait_for=">>>"
session_interact session_id="e5f6g7h8"  input="df.describe()"  wait_for=">>>"
session_close    session_id="e5f6g7h8"

데이터베이스 쿼리

session_create   command="psql -U admin mydb"  label="db"
session_interact session_id="x1y2z3w4"  input="SELECT count(*) FROM users;"  wait_for="row"
session_interact session_id="x1y2z3w4"  input="\dt"  wait_for="#"
session_close    session_id="x1y2z3w4"

TUI 앱 탐색

session_create   command="htop"  label="monitor"
session_read     session_id="a1b2c3d4"
# Auto-detects TUI, returns screen snapshot

session_send     session_id="a1b2c3d4"  key="F6"
session_read     session_id="a1b2c3d4"  mode="diff"
# Returns only changed lines - saves tokens

session_send     session_id="a1b2c3d4"  key="F10"
session_close    session_id="a1b2c3d4"

장기 실행 빌드 모니터링

session_create   command="bash"  label="build"
session_send     session_id="a1b2c3d4"  input="npm run build"
session_wait_for session_id="a1b2c3d4"  pattern="Build complete|ERROR"  timeout=120

일회성 명령어 실행

session_exec  exec="git log --oneline -10"
session_exec  exec="docker compose ps"  timeout=10

주요 기능

기능

설명

지속적인 세션

도구 호출 간에도 유지되는 실제 PTY 세션

한 번의 호출로 전송 + 읽기

session_interact가 LLM 왕복 시간을 절반으로 줄임

패턴 기반 읽기

wait_for가 정규식과 일치할 때까지 차단 - 시간 초과 추측 불필요

자동 TUI 감지

htop, vim 등을 감지하고 자동으로 화면 스냅샷 모드로 전환

출력 차이 모드

변경된 화면 줄만 반환 - 토큰 최소화

특수 키

화살표 키, Tab, F1-F12, Home/End, Page Up/Down

제어 문자

Ctrl-C, Ctrl-D, Ctrl-Z, Ctrl-L, telnet 이스케이프

위험 명령어 차단

rm -rf, DROP TABLE, curl|sh 차단 - 확인 필요

OSC 133 셸 통합

명령어 경계와 종료 코드 자동 감지

스마트 잘라내기

컨텍스트 오버플로를 방지하는 네 가지 전략

비밀 입력

비밀번호를 로깅 없이 전송

동적 크기 조정

SIGWINCH로 터미널을 즉시 크기 조정

유휴 정리

유휴 세션 자동 종료

크로스 플랫폼

Linux, macOS, Windows 지원

도구 참조

terminal-mcp는 9개의 MCP 도구를 제공합니다. 자세한 내용은 docs/tools.md에서 확인하세요.

도구

목적

session_create

지속적인 터미널 세션 생성

session_send

텍스트, 키 또는 제어 문자 전송

session_read

출력 읽기 (스트림, 스냅샷, 자동, 차이 모드)

session_interact

한 번의 호출로 전송 + 읽기

session_wait_for

출력에서 정규식 패턴 대기

session_exec

일회성 명령어 실행

session_close

세션을 정상적으로 종료

session_resize

터미널 크기 조정

session_list

활성 세션 목록 보기

아키텍처

flowchart LR
    Client[AI Client] -->|MCP JSON-RPC| Server[terminal-mcp]
    Server --> SM[Session Manager]
    SM --> S1[PTY 1: bash]
    SM --> S2[PTY 2: python3]
    SM --> S3[PTY 3: ssh user@host]
    S1 & S2 & S3 -.->|PTY output| Reader[Reader Thread]
    Reader -.->|buffer| Server

각 세션은 pexpect.spawn(Windows의 경우 PopenSpawn)을 통해 실제 PTY로 지원됩니다. 전체 아키텍처 세부 정보는 docs/architecture.md에서 확인하세요.

설정

모든 설정은 TERMINAL_MCP_* 환경 변수를 통해 구성 가능합니다. 전체 참조는 docs/configuration.md에서 확인하세요.

설정

환경 변수

기본값

최대 세션

TERMINAL_MCP_MAX_SESSIONS

10

유휴 시간 초과

TERMINAL_MCP_IDLE_TIMEOUT

1800 (30분)

안전 게이트

TERMINAL_MCP_SAFETY_GATE

on

버퍼 용량

TERMINAL_MCP_MAX_BUFFER_BYTES

1000000 (1MB)

잘라내기

TERMINAL_MCP_TRUNCATION_MODE

tail

사용자 설정 예시:

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"],
      "env": {
        "TERMINAL_MCP_MAX_SESSIONS": "20",
        "TERMINAL_MCP_IDLE_TIMEOUT": "3600",
        "TERMINAL_MCP_TRUNCATION_MODE": "head_tail"
      }
    }
  }
}

문서

문서

설명

도구 참조

9개 MCP 도구의 전체 API

아키텍처

terminal-mcp의 내부 작동 방식

설정

모든 설정 및 환경 변수

안전 및 보안

위험 명령어 감지 및 안전 게이트

사용 사례 및 예제

실제 레시피와 패턴

변경 로그

버전 기록 및 릴리스 노트

기여하기

기여 방법

지원되는 클라이언트

클라이언트

상태

설치

Claude Code (CLI)

지원됨

~/.claude.json 또는 .mcp.json

Claude Desktop

지원됨

원클릭 설치

VS Code (Copilot Chat)

지원됨

원클릭 설치 또는 .vscode/mcp.json

Cursor

지원됨

원클릭 설치 또는 설정

Windsurf

지원됨

~/.codeium/windsurf/mcp_config.json

테스트 실행

pip install -e ".[dev]"
pytest tests/ -v

기여하기

기여는 환영합니다! 지침은 docs/contributing.md를 참조하세요.

라이선스

MIT

Install Server
A
license - permissive license
A
quality
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
62dResponse time
6wRelease cycle
5Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • Interactive Terminal MCP

    Vltja
    A
    license
    -
    quality
    C
    maintenance
    Provides AI agents with fully interactive terminal sessions, including TUI support, keyboard control, and screen capture across Windows, Linux, and Mac.
    MIT

  • mcp-ssh-terminal

    zhdkirill
    A
    license
    -
    quality
    C
    maintenance
    Enables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.
    23
    1
    MIT

View all related MCP servers

Related MCP Connectors

  • SentinelX MCP

    Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.

  • emisar

    Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.

  • Corebee AI Customer Support

    Run AI customer support from your terminal: conversations, knowledge base, and chat widget.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mkpvishnu/terminal-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server