Interactive Terminal Server

PyPI version License: MIT

A fully interactive terminal MCP server for AI agents with TUI support, keyboard control, and screen capture - Cross-platform (Windows, Linux, Mac).

✨ Features

• 🖥️ Full Terminal Control - Create, manage, and delete terminal sessions
• ⌨️ Keyboard Support - Arrow keys, Ctrl, Alt, F-keys, PageUp/Down, etc.
• 📺 TUI Applications - Works with htop, vim, nano, mc, and more
• 🔄 Auto-Update - Automatically checks and installs updates from PyPI
• 🌍 Cross-Platform - Windows (pywinpty), Linux/Mac (ptyprocess)

📦 Installation

pip install vitjas-interactive-terminal

🚀 Usage

Start the MCP Server

You can start the server in 3 ways:

# Option 1: Entry Point (recommended)
vitjas-interactive-terminal

# Option 2: Python Module
python -m interactive_terminal

# Option 3: Python3 Module (Linux/Mac)
python3 -m interactive_terminal

MCP Configuration

For Claude Desktop / Agent Zero:

Linux/Mac (Option A - Entry Point):

{
  "mcpServers": {
    "InteractiveTerminal": {
      "command": "vitjas-interactive-terminal",
      "args": [],
      "init_timeout": 30
    }
  }
}

Linux/Mac (Option B - Python3 Module):

{
  "mcpServers": {
    "InteractiveTerminal": {
      "command": "python3",
      "args": ["-m", "interactive_terminal"],
      "init_timeout": 30
    }
  }
}

Windows:

{
  "mcpServers": {
    "InteractiveTerminal": {
      "command": "python",
      "args": ["-m", "interactive_terminal"],
      "init_timeout": 30
    }
  }
}

🛠️ Available Tools

Tool	Description
create_terminal	Create a new interactive terminal session
send_text	Send text/commands to a terminal
send_keys	Send special keys (arrows, Ctrl+C, etc.)
get_screen	Read terminal screen content
list_terminals	List all active terminals
delete_terminal	Delete/close a terminal
search_buffer	Search through terminal history

⌨️ Supported Keys

• Navigation: up, down, left, right, home, end, pageup, pagedown
• Control: ctrl+c, ctrl+d, ctrl+z, ctrl+a, ctrl+e, ctrl+u, ctrl+k, ctrl+w, ctrl+l
• Alt: alt+f, alt+b, alt+d
• Other: enter, escape, tab, backspace, delete, f1-f12

💡 Examples

Navigate htop:

# Create terminal and start htop
create_terminal → send_text("htop\n") → get_screen()
# Navigate with arrow keys
send_keys("down") → send_keys("enter")
# Exit
send_keys("f10") or send_keys("q")

Edit with nano:

# Create and open file
create_terminal → send_text("nano test.txt\n")
# Type content
send_text("Hello World!")
# Save and exit
send_keys("ctrl+x") → send_text("Y") → send_keys("enter")

🔧 Configuration

Disable Auto-Update:

VITJAS_AUTO_UPDATE=false vitjas-interactive-terminal

📋 Requirements

• Python >= 3.10
• Windows: pywinpty >= 2.0.0 (auto-installed)
• Linux/Mac: ptyprocess >= 0.7.0 (auto-installed)

🔗 Links

• PyPI: https://pypi.org/project/vitjas-interactive-terminal/
• GitHub: https://github.com/Vltja/vitjas-interactive-terminal
• Issues: https://github.com/Vltja/vitjas-interactive-terminal/issues

📜 License

MIT License - see LICENSE

👤 Author

Vltja - GitHub