Terminal MCP

공식

AI 어시스턴트에게 터미널 세션의 공유 실시간 보기를 제공하여 CLI 및 TUI 디버깅이나 자율 터미널 제어를 지원합니다.

GitHub

132

이 MCP 사용해 보기스폰서

Terminal MCP(으)로 무엇을 할 수 있나요?

명령 입력 및 키 전송 — AI가 type 및 sendKey를 통해 셸 명령을 실행하도록 요청하며, Enter 또는 Ctrl+C와 같은 특수 키도 포함합니다.
터미널 출력 읽기 — getContent로 현재 터미널 버퍼를 일반 텍스트로 검색하거나, takeScreenshot을 통해 text, ansi 또는 png 형식으로 스크린샷을 캡처합니다.
세션 기록 및 재생 — startRecording 및 stopRecording으로 asciicast v2 녹화를 시작 및 중지한 다음, asciinema로 재생합니다.
여러 세션 관리 — createSession으로 격리된 터미널 세션을 만들고, listSessions로 활성 세션을 나열하며, destroySession으로 정리합니다. 각 세션은 sessionId로 식별됩니다.

문서

AI가 여러분의 터미널을 보고 상호작용할 수 있게 하세요.

Terminal MCP는 LLM에게 터미널 세션의 공유 뷰를 제공합니다. CLI 및 TUI 애플리케이션을 실시간으로 디버깅하거나, AI가 터미널 기반 도구를 자율적으로 구동하게 하는 데 완벽합니다.

설치

npm install -g @ellery/terminal-mcp

또는 설치 스크립트를 통해:

curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash

AI 도구 구성

terminal-mcp를 컴퓨터에 설치된 모든 AI 도구의 MCP 구성에 한 번에 연결하세요:

terminal-mcp setup                      # detect & install for all detected tools
terminal-mcp setup --dry-run            # preview without writing
terminal-mcp setup --client claude-code,gemini   # specific tools only
terminal-mcp setup --uninstall          # remove the entry from each tool

지원되는 클라이언트 (각각 해당 구성 형식에 맞는 올바른 스키마를 받습니다):

클라이언트	구성 파일	형식
OpenAI Codex CLI	`~/.codex/config.toml`	TOML
GitHub Copilot CLI	`~/.copilot/mcp-config.json`	JSON
Gemini CLI	`~/.gemini/settings.json`	JSON
OpenCode	`~/.config/opencode/opencode.json`	JSON
Claude Code	`~/.claude.json`	JSON
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows)	JSON

기존 구성의 .bak는 최초 설치 시 원본 옆에 기록됩니다. terminal-mcp 항목은 다른 서버나 관련 없는 키를 방해하지 않고 추가됩니다. setup를 다시 실행하는 것은 아무 작업도 수행하지 않습니다.

업그레이드

npm install -g @ellery/terminal-mcp@latest

대화형 모드는 최신 릴리스가 있을 때 다음 실행 시 배너를 출력합니다 — terminal-mcp는 npm 레지스트리를 하루에 한 번 확인하고 결과를 캐시합니다. 헤드리스 및 MCP 클라이언트 모드는 확인하거나 출력하지 않습니다 (MCP stdio를 깨끗하게 유지). 완전히 제외하려면 NO_UPDATE_NOTIFIER=1를 설정하거나 --no-update-notifier를 전달하세요.

기능

전체 터미널 에뮬레이션: 정확한 VT100/ANSI 에뮬레이션을 위해 xterm.js 헤드리스 사용
크로스 플랫폼 PTY: node-pty를 통한 네이티브 의사 터미널 지원 (macOS, Linux, Windows)
MCP 프로토콜: AI 어시스턴트 통합을 위한 Model Context Protocol 구현
세션 녹화: asciinema으로 재생할 수 있는 asciicast 형식으로 터미널 세션 녹화
간단한 API: 입력, 관찰, 녹화 및 세션 수명 주기를 다루는 9가지 도구
헤드리스 모드: TTY 없이 독립형 MCP 서버로 실행 — CI, 컨테이너 및 비대화형 환경에 이상적
멀티 세션: 하나의 프로세스에서 sessionId로 주소가 지정된 여러 격리된 터미널 세션 실행
샌드박스 모드: 파일 시스템 및 네트워크 액세스에 대한 선택적 보안 제한

소스에서 빌드

npm install
npm run build

사용법

MCP 구성

MCP 클라이언트 설정에 추가:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp"
    }
  }
}

사용자 지정 옵션 포함:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--cols", "100", "--rows", "30", "--shell", "/bin/zsh"]
    }
  }
}

명령줄 옵션

terminal-mcp [OPTIONS]

Options:
  --cols <number>        Terminal width in columns (default: 120)
  --rows <number>        Terminal height in rows (default: 40)
  --shell <path>         Shell to use (default: $SHELL or bash)
  --headless             Run in headless mode (embedded PTY + MCP over stdio, no TTY needed)
  --sandbox              Enable sandbox mode (restricts filesystem/network)
  --sandbox-config <path> Load sandbox config from JSON file
  --version, -v          Show version number
  --help, -h             Show help message

Recording Options:
  --record [mode]     Enable recording (default mode: always)
                      Modes: always, on-failure, off
  --record-dir <dir>  Recording output directory
                      (default: ~/.local/state/terminal-mcp/recordings)
  --idle-time-limit <sec>   Max idle time between events (default: 2s)
  --max-duration <sec>      Max recording duration (default: 3600s)
  --inactivity-timeout <sec>  Stop after no output (default: 600s)

Multi-Session Options:
  --max-sessions <n>           Max concurrent sessions (default: 5)
  --session-idle-timeout <sec> Idle non-default sessions are auto-destroyed
                               after this period (default: 600s)

헤드리스 모드

기본적으로 Terminal MCP는 이중 프로세스 아키텍처를 사용합니다: 대화형 터미널에서 terminal-mcp를 실행하고 (Unix 소켓을 생성), MCP 클라이언트가 해당 소켓에 연결하는 두 번째 인스턴스를 생성합니다. 이는 TTY가 필요합니다.

헤드리스 모드 (--headless)는 내부적으로 임베디드 PTY를 생성하고 단일 프로세스에서 stdio를 통해 MCP를 직접 제공하여 이 요구 사항을 제거합니다. 대화형 터미널 세션, 소켓 없이 — 내장 터미널이 있는 자체 포함 MCP 서버만 있습니다.

헤드리스 모드를 사용해야 하는 경우

CI/CD 파이프라인 — TTY 사용 불가
Docker 컨테이너 — 함께 실행할 대화형 셸 없음
원격/클라우드 환경 — 자동화에 의해 생성된 MCP 서버
간소화된 설정 — 단일 프로세스, 소켓 조정 불필요

구성

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--headless", "--cols", "120", "--rows", "40"]
    }
  }
}

작동 방식

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP Server (stdio transport)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

헤드리스 모드에서 터미널 세션은 시작 시 즉시 초기화되므로 모든 도구 (type, sendKey, getContent, takeScreenshot, startRecording, stopRecording, createSession, listSessions, destroySession)를 즉시 사용할 수 있습니다.

MCP 도구

모든 입출력 도구 (type, sendKey, getContent, takeScreenshot)는 선택적 sessionId 인수를 허용합니다. 기본 세션을 대상으로 하려면 생략하고, 특정 세션을 구동하려면 createSession가 반환한 ID를 전달하세요.

`type`

터미널에 텍스트 입력을 보냅니다.

{
  "name": "type",
  "arguments": {
    "text": "echo hello"
  }
}

`sendKey`

특수 키 또는 키 조합을 보냅니다.

{
  "name": "sendKey",
  "arguments": {
    "key": "Enter"
  }
}

지원되는 키:

기본: Enter, Tab, Escape, Backspace, Delete
화살표: ArrowUp, ArrowDown, ArrowLeft, ArrowRight
탐색: Home, End, PageUp, PageDown, Insert
기능: F1부터 F12까지
제어: Ctrl+A부터 Ctrl+Z까지, Ctrl+C, Ctrl+D 등

`getContent`

터미널 버퍼를 일반 텍스트로 가져옵니다.

{
  "name": "getContent",
  "arguments": {
    "visibleOnly": false
  }
}

`takeScreenshot`

터미널 상태를 캡처합니다. 세 가지 출력 형식을 지원합니다:

형식	설명
`text` (기본값)	일반 텍스트 내용, 커서 위치 및 크기가 포함된 JSON
`ansi`	내용 필드에 ANSI 색상 이스케이프 시퀀스가 보존된 JSON
`png`	PNG 이미지로 된 컬러 스크린샷 (`@resvg/resvg-js` 필요)

{
  "name": "takeScreenshot",
  "arguments": { "format": "text" }
}

ansi 형식은 터미널의 셀 버퍼에서 SGR 이스케이프 시퀀스를 재구성하여 16색, 256색 및 24비트 트루컬러 속성과 굵게, 흐리게, 기울임꼴 및 밑줄 스타일을 보존합니다.

png 형식은 One Dark 색상 테마와 macOS 스타일 창 크롬으로 렌더링된 base64 인코딩 PNG 데이터가 포함된 MCP image 콘텐츠 블록을 반환합니다.

`startRecording`

터미널 출력을 asciicast v2 파일로 녹화를 시작합니다.

{
  "name": "startRecording",
  "arguments": {
    "mode": "always",
    "idleTimeLimit": 2,
    "maxDuration": 3600
  }
}

옵션:

mode: always (모두 저장) 또는 on-failure (0이 아닌 종료 코드일 때만 저장)
outputDir: 사용자 지정 출력 디렉터리
idleTimeLimit: 이벤트 사이 최대 초 (재생 중 일시 중지 상한)
maxDuration: N초 후 자동 중지
inactivityTimeout: 출력 없이 N초 후 자동 중지

`stopRecording`

녹화를 중지하고 asciicast 파일을 마무리합니다.

{
  "name": "stopRecording",
  "arguments": {
    "recordingId": "abc123"
  }
}

`createSession`

새 터미널 세션을 만들고 해당 메타데이터를 반환합니다. 반환된 sessionId를 사용하여 후속 도구 호출에서 이 세션을 대상으로 지정하세요.

{
  "name": "createSession",
  "arguments": {
    "shell": "/bin/zsh",
    "cols": 100,
    "rows": 30
  }
}

모든 인수는 선택 사항입니다. 반환:

{
  "sessionId": "3029d",
  "shell": "/bin/zsh",
  "cols": 100,
  "rows": 30,
  "createdAt": "2026-04-25T12:58:01.072Z",
  "lastActivityAt": "2026-04-25T12:58:01.072Z",
  "isDefault": false
}

`listSessions`

기본 세션을 포함한 모든 활성 세션을 나열합니다. 구성된 제한을 보고합니다.

{ "name": "listSessions", "arguments": {} }

`destroySession`

ID로 세션을 삭제합니다. 기본 세션은 삭제할 수 없습니다.

{
  "name": "destroySession",
  "arguments": { "sessionId": "3029d" }
}

멀티 세션

기본적으로 sessionId 없는 모든 도구 호출은 단일 자동 생성 기본 세션을 대상으로 합니다 — 프로젝트가 항상 가져온 동작과 동일합니다. sessionId를 전달하여 하나의 프로세스에서 여러 격리된 PTY를 구동하세요.

기본 세션은 첫 사용 시 생성되며 삭제할 수 없습니다.
추가 세션은 createSession로 생성되며 삭제되거나 유휴 상태로 퇴거될 때까지 추적됩니다 (--session-idle-timeout, 기본 600초).
동시 세션은 --max-sessions (기본 5)로 제한됩니다.
활성 녹화는 프로세스의 모든 세션에서 출력을 캡처합니다.

일반적인 사용 사례: AI 에이전트가 한 세션에서 장기 실행 빌드를 구동하면서 다른 세션에서 진단을 실행하고, 명령이 섞이지 않도록 하는 것입니다.

샌드박스 모드

제한된 파일 시스템 및 네트워크 액세스로 터미널을 실행:

# Interactive permission configuration
terminal-mcp --sandbox

# With a config file
terminal-mcp --sandbox --sandbox-config ~/.terminal-mcp-sandbox.json

대화형 모드는 권한을 구성하는 TUI 대화 상자를 표시합니다:

Sandbox Permissions Dialog

- **읽기/쓰기**: 전체 액세스 (현재 디렉터리, /tmp, 캐시) - **읽기 전용**: 읽을 수 있지만 수정할 수 없음 (홈 디렉터리) - **차단됨**: 액세스 없음 (SSH 키, 클라우드 자격 증명, 인증 토큰)

구성 파일 예시:

{
  "filesystem": {
    "readWrite": [".", "/tmp", "~/.cache"],
    "readOnly": ["~"],
    "blocked": ["~/.ssh", "~/.aws", "~/.gnupg"]
  },
  "network": {
    "mode": "all"
  }
}

플랫폼 지원:

macOS: sandbox-exec (Seatbelt)를 통한 전체 지원
Linux: bubblewrap를 통한 전체 지원 (bwrap 설치 필요)
Windows: 정상적인 대체 (샌드박스 없이 실행)

자세한 구성 옵션은 샌드박스 문서를 참조하세요.

녹화

Terminal MCP는 재생을 위해 asciinema와 호환되는 asciicast v2 형식으로 세션을 녹화할 수 있습니다.

빠른 시작

# Start with recording enabled
terminal-mcp --record

# Run your commands, then exit
exit

# Output shows the saved file path:
# Recordings saved:
#   ~/.local/state/terminal-mcp/recordings/20240115_143022.cast
#
# Play with: asciinema play <file>

재생

녹화를 재생하려면 asciinema를 설치하세요:

# macOS
brew install asciinema

# Linux/pip
pip install asciinema

# Play a recording
asciinema play ~/.local/state/terminal-mcp/recordings/20240115_143022.cast

# Play at 2x speed
asciinema play -s 2 recording.cast

녹화 모드

always (기본값): 모든 녹화 저장
on-failure: 세션이 0이 아닌 코드로 종료될 때만 저장 (실패한 CI 실행 디버깅에 유용)

# Only save recordings when something fails
terminal-mcp --record=on-failure

MCP 도구 녹화

AI 어시스턴트는 MCP 도구를 통해 프로그래밍 방식으로 녹화를 제어할 수도 있습니다:

startRecording를 호출하여 캡처 시작
터미널 작업 수행
stopRecording를 호출하여 마무리 및 저장

이를 통해 "이 디버깅 세션 녹화" 또는 "이 데모 캡처"와 같은 AI 기반 워크플로가 가능합니다.

아키텍처

Terminal MCP에는 세 가지 작동 모드가 있습니다:

모드	플래그	표준 입력	설명
대화형	(기본값)	TTY	사용자가 셸을 얻음; AI가 Unix 소켓을 통해 연결
클라이언트	(기본값)	비-TTY	대화형 세션의 소켓에 연결, stdio를 통해 MCP 제공
헤드리스	`--headless`	모든	자체 포함: 임베디드 PTY + stdio를 통한 MCP 서버

헤드리스 모드 (MCP 구성에 권장)

MCP Client (Claude Code, etc.)
    │ STDIO (JSON-RPC)
    ▼
terminal-mcp --headless
    ├── MCP SDK (@modelcontextprotocol/sdk)
    ├── Terminal Emulator (@xterm/headless)
    └── Embedded PTY (node-pty)
            │
            ▼
        Shell Process (bash, zsh, etc.)

대화형 + 클라이언트 모드 (이중 프로세스)

terminal-mcp (interactive, in your terminal)
    ├── User shell (stdin/stdout)
    └── Unix socket server (/tmp/terminal-mcp.sock)
            ▲
            │ JSON-RPC over socket
            ▼
terminal-mcp (client, spawned by MCP client)
    └── MCP server (stdio transport)

예제 세션

# Type a command
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"type","arguments":{"text":"ls -la"}}}

# Send Enter key
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sendKey","arguments":{"key":"Enter"}}}

# Get the output
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getContent","arguments":{}}}

개발

npm run build    # Compile TypeScript
npm run dev      # Run with tsx (development)

문서

자세한 문서는 docs 폴더를 참조하세요:

요구 사항

Node.js 18.0.0 이상
Windows 10 버전 1809 이상 (ConPTY 지원용)

라이선스

MIT