Interactive Shell

Provides interactive, persistent PTY shell sessions with full terminal emulation for LLM-driven command execution.

typescript

4

GitHub Stars

typescript

Language

5 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can run and manage interactive shell sessions for large language models with this MCP server. It creates persistent PTY-based shells, supports full terminal emulation, and lets you interact with interactive programs as if you were typing in a real terminal. This enables complex workflows that require an evolving terminal state across multiple commands.

How to use

Start a new interactive shell session with a dedicated PTY. You can open multiple sessions simultaneously to run different tasks in parallel.

Send input to any active session as if you were typing in a terminal. The server handles newline characters automatically, so you can issue commands just like you would in a real shell.

Read output from a session in one of two modes. Default is streaming mode, which returns new output since the last read and clears the internal buffer. For long-running or continuously updating programs (such as top, htop, or other full-screen applications), switch to snapshot mode to capture the current screen state without clearing the terminal.

If you need to terminate a session, close it to clean up resources. All session data is isolated and does not leak between sessions.

Tip: For programs that constantly update the display, snapshot mode helps you capture the current UI state without losing the ability to resume interaction later.

How to install

Prerequisites: you need Node.js and npm installed on your system.

Install dependencies and build the MCP server.

Run the server locally for testing or development.

Configuration and usage notes

Configure the MCP client to connect to the local or remote server as instructed by your integration. If you are integrating with Claude Desktop or VS Code, you can provide a local stdio-based command to start the server process.

Examples and practical tips

Working with high-output commands benefits from snapshot mode to prevent missing updates in rapidly changing displays. Regular commands can use streaming mode for timely feedback.

Available tools

start_shell_session

Opens a new PTY shell instance and returns a unique session ID to manage the session.

send_shell_input

Sends input to the active PTY, handling newlines automatically to simulate typing in a real terminal.

read_shell_output

Retrieves output from the PTY. Supports streaming mode (returns new output since last read) and snapshot mode (returns the current screen state without clearing).

end_shell_session

Closes the PTY and frees all associated resources for a session.