Skip to main content
Glama

interactive-cli

An MCP server that runs commands in a real pseudo-terminal and hands your AI agent the rendered screen, so it can answer prompts, pick menu items and drive REPLs, SSH and installers the way you would.

npm license: MIT MCP server

Site: https://ohernandezdev.github.io/interactive-cli/

Works with Claude Code, Codex, Cursor, Windsurf, or any MCP client that speaks stdio.

Why

A shell tool sends a command and waits for it to finish. An interactive command never finishes: it waits for a person. The agent hangs, times out or kills it, and you end up typing the answer yourself.

$ npm init
package name: (my-app)
waiting for input…

interactive-cli bridges that gap. It spawns the process in a PTY, renders the screen with xterm headless (clean text, no ANSI escape soup), and lets the agent send input or keys and wait for patterns.

Related MCP server: pty-mcp

Install

Requires Node 18 or later, on macOS or Linux.

Claude Code

claude mcp add interactive-cli -- npx -y interactive-cli-mcp

Codex CLI

codex mcp add interactive-cli -- npx -y interactive-cli-mcp

This writes [mcp_servers.interactive-cli] with command = "npx" and args = ["-y", "interactive-cli-mcp"] to ~/.codex/config.toml.

Cursor

Add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "interactive-cli": {
      "command": "npx",
      "args": ["-y", "interactive-cli-mcp"]
    }
  }
}

Any MCP client

Point a stdio MCP client at:

npx -y interactive-cli-mcp

From source

git clone https://github.com/ohernandezdev/interactive-cli.git
cd interactive-cli
npm install && npm run build
claude mcp add interactive-cli -- node /absolute/path/to/interactive-cli/dist/index.js

What a session looks like

An illustrative eas build session. The agent calls the tools; the server answers with the rendered screen.

spawn("eas build --platform ios")
  ? Select a build profile ›
  ❯ development
    preview
    production

get_screen()
  (same screen)

send_keys(["down", "down", "enter"])
  ✔ Selected profile: production
  ? Do you want to log in to your Apple account? › (Y/n)

send_input("y")
  ✔ Logged in
  Building…

wait_for("Build complete|error", 600000)
  ✔ Build complete

close()
  exit 0

(sessionId is omitted above for brevity; every call after spawn takes the id that spawn returned.)

Tools

Tool

Parameters (defaults)

Read-only

spawn

command, cwd?, env?, cols = 120, rows = 30, waitMs = 2000

No

send_input

sessionId, text, pressEnter = true, waitMs = 2000

No

send_keys

sessionId, keys[], delayBetweenMs = 50, waitMs = 1500

No

get_screen

sessionId, search?, waitMs = 500

Yes

wait_for

sessionId, pattern, timeoutMs = 30000, intervalMs = 1000

No

wait_for_exit

sessionId, timeoutMs = 30000

No

resize

sessionId, cols, rows

No

list_sessions

none

Yes

close

sessionId

No

  • spawn runs the command as $SHELL -c "<command>" (/bin/zsh when SHELL is unset), so pipes, redirects and builtins work. env is merged with the current environment. waitMs is how long to wait for the first output.

  • send_input appends Enter unless pressEnter is false, which types without submitting (useful for forms and password fields).

  • send_keys sends the keys in order with delayBetweenMs between them, then waits waitMs.

  • get_screen waits waitMs before capturing (default 500; 0 for an instant capture). search is a regex: the result adds the matching lines with 2 lines of context.

  • wait_for takes a regex, matched case-insensitively. Use a long timeoutMs for builds.

  • close sends SIGTERM, then SIGKILL if needed, and returns the final screen.

  • spawn, send_input, send_keys and close are annotated as destructive, so clients such as Claude Code ask before using them. get_screen and list_sessions are annotated read-only.

  • Every result is JSON.

Keys

send_keys accepts: enter tab escape space up down left right backspace delete home end page_up page_down f1 to f12 ctrl+c ctrl+d ctrl+z ctrl+l ctrl+a ctrl+e ctrl+r ctrl+w ctrl+u ctrl+k ctrl+p ctrl+n y n 0 to 9

Resources

  • interactive-cli://sessions: JSON list of all sessions

  • interactive-cli://sessions/{sessionId}/screen: live screen content of a session (text/plain)

Prompts

Prompt templates for common flows. In Claude Code they appear as slash commands (/mcp__interactive-cli__eas_build).

Prompt

Arguments

eas_build

platform? (default ios), profile? (default production), cwd?

ssh_session

host (user@hostname), commands? (semicolon-separated)

repl_session

command (python3, node, psql, ...), setup? (semicolon-separated)

docker_interactive

image, shellCmd? (default /bin/sh)

eas_build runs eas build --platform <platform> --profile <profile> --auto-submit. docker_interactive runs docker run -it <image> <shellCmd>.

How it works

graph LR
    A[AI Agent] <-->|MCP Protocol| B[interactive-cli server]
    B --> C[Session Manager]
    C --> D[node-pty<br/><i>real PTY</i>]
    C --> E[xterm headless<br/><i>screen render</i>]
    C --> F[Truncation<br/><i>80K limit</i>]
    D <--> G[Child Process<br/>ssh, eas, python...]
  • node-pty spawns a real pseudo-terminal (xterm-256color), so the child process behaves as it does in your terminal.

  • xterm headless keeps a virtual terminal (1,000 lines of scrollback) and renders it into a clean 2D text grid.

  • Screens are capped at 80,000 characters, cut in the middle with a marker so the start and the end survive. Claude Code caps tool results at 100,000.

Typical flow:

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as interactive-cli
    participant PTY as Process (PTY)

    Agent->>MCP: spawn("eas build --platform ios")
    MCP->>PTY: Start process in PTY
    PTY-->>MCP: Initial output
    MCP-->>Agent: sessionId + screen

    Agent->>MCP: send_keys(["down","down","enter"])
    MCP->>PTY: ↓ ↓ ⏎
    PTY-->>MCP: "✔ Selected profile: production"
    MCP-->>Agent: updated screen

    Agent->>MCP: wait_for("Build complete|error", 600000)
    PTY-->>MCP: "✔ Build complete"
    MCP-->>Agent: matched + screen

    Agent->>MCP: close(sessionId)
    MCP->>PTY: SIGTERM
    MCP-->>Agent: final screen + exit code

Limits

  • macOS and Linux only. Commands run through your shell ($SHELL -c), and Windows is not supported.

  • Any screen in a result is capped at 80,000 characters.

  • Scrollback is 1,000 lines.

  • The agent runs commands with your permissions, in your shell. Review what your client approves.

Development

npm install
npm run build
node dist/index.js

Dependencies: @modelcontextprotocol/sdk, node-pty, @xterm/headless, zod.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage interactive pseudo-terminal (PTY) sessions for programs requiring full terminal emulation like vim, ssh, and interactive REPLs. It provides tools to spawn sessions, send input with escape sequences, and read buffered terminal output.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a pseudo-terminal (PTY) interface that allows AI agents to interact with command-line tools requiring interactive prompts. It enables agents to autonomously spawn processes, read output, and send inputs for workflows like database migrations and project scaffolding.
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI agents to start and manage pseudo-terminal sessions, run shell commands and interact with REPLs programmatically.
      7
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to spawn persistent terminal sessions, send keystrokes, read screen state, and assert output, allowing them to interact with stateful terminal applications like vim, htop, and gdb.
      28 npm
      MIT