interactive-process-mcp

MCP server for managing interactive processes. Allows AI agents (Claude Code, etc.) to start long-running interactive programs — SSH sessions, REPLs, installers, impacket tools — and interact with them over multiple turns via read/write operations.

Features

• PTY & Pipe modes — PTY mode emulates a real terminal (programs like SSH, top, vim work correctly); pipe mode for simpler stdin/stdout interaction

• Multi-session — manage multiple interactive processes simultaneously

• ANSI stripping — optional removal of terminal escape codes for clean output

• Non-blocking reads — agent reads output at its own pace with configurable timeouts

• Graceful shutdown — SIGTERM with configurable grace period before SIGKILL

Requirements

• Python >= 3.10

• Linux (uses pty module)

Installation

pip install -e .

Or with dev dependencies (for running tests):

pip install -e ".[dev]"

Configuration

Claude Code

command

claude mcp add --scope user interactive-process -- interactive-process-mcp

Or

Add to your Claude Code MCP settings (.claude/settings.json or project-level .mcp.json):

{
  "mcpServers": {
    "interactive-process": {
      "command": "interactive-process-mcp"
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "interactive-process": {
      "command": "python",
      "args": ["-m", "interactive_process_mcp"]
    }
  }
}

Other MCP Clients

Any MCP client that supports stdio transport can use this server. The entry point is:

interactive-process-mcp
# or
python -m interactive_process_mcp

Tools

start_process

Start an interactive process and return its session info.

Returns: { session_id, pid, initial_output }

send_input

Send text to a running process.

Returns: { success: true } or { error: "..." }

read_output

Read new output since the last read. If no new output is available, waits up to timeout seconds. Returns empty on timeout (not an error).

Returns: { output, has_more, lines_returned, bytes_returned }

send_and_read

Atomic send + read. Sends input, waits briefly, then returns new output.

Combines parameters from send_input and read_output.

list_sessions

List all active sessions.

Returns: { sessions: [{ id, name, command, status, pid, created_at }] }

terminate_process

Terminate a running process.

resize_pty

Resize the PTY dimensions (pty mode only).

get_session_info

Get detailed info about a session.

Returns: { id, name, command, args, mode, status, exit_code, pid, created_at }

Usage Examples

SSH Session

1. start_process(command="ssh", args=["user@host"], mode="pty")
   → { session_id: "abc123", initial_output: "user@host's password: " }

2. send_input(session_id="abc123", text="mypassword", press_enter=true)
   → { success: true }

3. read_output(session_id="abc123", timeout=5)
   → { output: "Welcome to Ubuntu...\n$ " }

4. send_and_read(session_id="abc123", text="ls -la", press_enter=true, timeout=3)
   → { output: "total 32\ndrwxr-xr-x ...\n$ " }

5. terminate_process(session_id="abc123")
   → { success: true }

Python REPL

1. start_process(command="python3", mode="pty")
   → { session_id: "def456", initial_output: ">>> " }

2. send_and_read(session_id="def456", text="print(2 + 2)", press_enter=true)
   → { output: "4\n>>> " }

Interactive Installer

1. start_process(command="sudo", args=["apt", "install", "some-package"], mode="pty")
   → { session_id: "ghi789", initial_output: "Do you want to continue? [Y/n] " }

2. send_input(session_id="ghi789", text="Y", press_enter=true)
   → { success: true }

3. read_output(session_id="ghi789", timeout=30)
   → { output: "Setting up some-package ...\n" }

Architecture

MCP Server (main thread — JSON-RPC over stdio)
  ├── Session reader thread → ring buffer → agent reads
  ├── Session reader thread → ring buffer → agent reads
  └── Session reader thread → ring buffer → agent reads

Each session runs its own background reader thread that continuously reads process output into a ring buffer (max ~1MB). The agent consumes output at its own pace via read_output / send_and_read.

Testing

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

License

MIT