대화형 셸 MCP

TUI를 지원하는 대화형 셸 세션을 위한 MCP 서버입니다. AI 에이전트에게 지속적인 터미널, 대화형 프롬프트 탐색, 렌더링된 화면 읽기 및 출력 검색 기능을 제공합니다.

데모

이 프로젝트의 존재 이유

대부분의 AI 코딩 도구는 셸 명령을 격리된 상태로 실행합니다. 각 명령은 새로운 셸을 시작하므로 대화형 프롬프트가 불가능하며, TUI 앱은 원시 이스케이프 코드만 출력합니다. 이 MCP 서버는 가상 터미널 에뮬레이터(@xterm/headless)를 갖춘 지속적인 PTY 세션을 제공하여, 에이전트가 셸 상태를 유지하고, 화살표 키로 대화형 프롬프트를 탐색하며, 렌더링된 터미널 화면을 깔끔한 텍스트로 읽을 수 있게 합니다.

세 가지 출력 모드:

빠른 시작

git clone https://github.com/lightos/interactive-shell-mcp.git
cd interactive-shell-mcp
npm install && npm run build
claude mcp add interactive-shell node dist/src/server.js

그런 다음 Claude에게 다음과 같이 물어보세요: "htop을 모니터링하고 CPU를 가장 많이 사용하는 프로세스가 무엇인지 알려줘"

기능

• @xterm/headless를 통한 TUI 앱의 렌더링된 화면 읽기

• 모든 읽기 도구에 걸친 waitForIdle 지원 (sleep으로 추측할 필요 없음)

• 텍스트 및 정규식 패턴 매칭을 통한 화면 검색

• 행/열 좌표를 사용한 직사각형 영역 추출

• 셸 허용 목록: bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe

• 10분 유휴 상태 후 자동 정리, 프로세스 종료 후 60초 동안 종료 코드 감지

• 크로스 플랫폼: Unix/Linux/macOS + Windows

사용 사례

• 대화형 스캐폴딩 및 마이그레이션: npx create-next-app, drizzle-kit push, prisma migrate, npm init 또는 inquirer/clack 기반 CLI

• 시스템 모니터링: 프로세스 검색 및 영역 추출이 가능한 htop, btop, top, iftop, duf

• DevOps TUI: lazydocker, lazygit, k9s, terraform console

• 원격 세션: SSH를 통한 서버 접속 (SSH를 통한 중첩 TUI 앱 포함)

• 데이터베이스 CLI: 대화형 모드의 psql, mysql, redis-cli, mongosh

• 네트워크 도구: netcat/ncat, nmap, airodump-ng, tcpdump

• REPL 및 디버거: python, node, irb, gdb/lldb

• 텍스트 편집기: vim, nano, emacs -nw

MCP 구성

Claude Code (CLI)

claude mcp add interactive-shell node /path/to/interactive-shell-mcp/dist/src/server.js

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json (Windows)에 추가하세요:

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

VS Code / Cursor

MCP 설정(.vscode/mcp.json 또는 ~/.cursor/mcp.json)에 추가하세요:

{
  "mcpServers": {
    "interactive-shell": {
      "command": "node",
      "args": ["/path/to/interactive-shell-mcp/dist/src/server.js"]
    }
  }
}

도구 참조

start_shell_session

가상 터미널 에뮬레이터가 포함된 새로운 PTY 셸을 생성합니다.

{ sessionId, cols, rows }를 반환합니다.

send_shell_input

PTY에 입력을 보냅니다. 기본적으로 캐리지 리턴이 추가됩니다.

read_shell_output

PTY에서 출력을 읽습니다. 세 가지 모드: 스트리밍(기본값), 스냅샷, 화면.

화면 모드는 메타데이터에 커서 위치, 터미널 크기, 대체 버퍼 상태를 반환합니다.

get_screen_region

화면의 직사각형 영역에서 텍스트를 추출합니다.

get_screen_cursor

커서 위치와 현재 줄 텍스트를 가져옵니다.

{ cursor: { x, y }, currentLine, isAlternateBuffer }를 반환합니다.

search_screen

터미널 화면에서 텍스트나 정규식을 검색합니다. 최대 50개의 결과를 반환합니다.

{ results: [{ row, col, text }], count }를 반환합니다.

list_sessions

메타데이터와 함께 모든 활성 세션을 나열합니다. 매개변수 없음.

{ sessions: [{ sessionId, shell, cols, rows, isAlternateBuffer, idleSeconds }] }를 반환합니다.

resize_shell

활성 세션의 터미널 크기를 조정합니다.

end_shell_session

PTY를 닫고 리소스를 정리합니다.

사용 예시

다음은 통합을 구축하는 개발자를 위한 MCP 도구 호출 패턴입니다. 최종 사용자는 AI 에이전트와 자연스럽게 대화하기만 하면 됩니다.

TUI 앱 읽기

await send_shell_input(sessionId, "htop");
const { output, metadata } = await read_shell_output(sessionId, {
  mode: "screen",
  waitForIdle: 500
});
// output: rendered htop as clean text (CPU bars, process table, etc.)
// metadata.isAlternateBuffer: true (htop uses alternate screen)

// Extract just the process list (rows 6-30)
const processes = await get_screen_region(sessionId, {
  startRow: 6, startCol: 0, endRow: 30, endCol: 120,
  trimWhitespace: true
});

대화형 프롬프트 탐색

// Send arrow keys and enter in raw mode
await send_shell_input(sessionId, "\\x1b[B", { raw: true });  // down arrow
await send_shell_input(sessionId, " ", { raw: true });         // space to select
await send_shell_input(sessionId, "\\r", { raw: true });       // enter to confirm

// Read what the prompt looks like now
const screen = await read_shell_output(sessionId, {
  mode: "screen", waitForIdle: 300
});

명령 출력 대기

await send_shell_input(sessionId, "npm install");
const output = await read_shell_output(sessionId, {
  waitForIdle: 1000  // wait for 1s of silence
});

콘텐츠 검색

// Find all error lines
const errors = await search_screen(sessionId, {
  pattern: "error|Error|ERROR",
  regex: true,
  waitForIdle: 500
});
// [{ row: 12, col: 0, text: "Error" }, ...]

세션 동작

• 자동 정리: 10분 이상 유휴 상태인 세션은 자동으로 삭제됩니다.

• 종료 감지: 셸이 종료되면 도구는 일반적인 잘못된 ID 오류 대신 60초 동안 "Session exited with code N"을 반환합니다.

• 셸 허용 목록: 알려진 셸(bash, zsh, fish, sh, dash, ksh, powershell.exe, pwsh, cmd.exe)만 생성할 수 있습니다. 알 수 없는 값은 플랫폼 기본값으로 대체됩니다.

라이선스

MIT