Labsco
dragoscirjan logo

MCP TUIKit

from dragoscirjan

A headless terminal and tmux interaction server for Model Context Protocol.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#scraping#browser#devops#git#maps

mcp-tuikit

Model Context Protocol server for Text User Interface (TUI) and headless terminal automation

A Model Context Protocol (MCP) server that enables AI agents (Claude Code, Cursor, Windsurf, OpenCode) to launch, interact with, and observe any terminal application in isolated sessions. mcp-tuikit uses tmux and various native terminal backends to let AI interact with complex TUIs like nvim, btop, lazygit, or standard shells, providing both text and visual (PNG) snapshotting of terminal states.

🚀 Fully Cross-OS Compatible: Works seamlessly across macOS, Linux, and Windows.

Table of Contents

Why mcp-tuikit?

  • Isolated Sessions: Each session runs in an isolated tmux environment. AI interactions do not leak into or disrupt your host terminal.
  • Headless & Visual: Capture accurate textual screen state and visual PNG screenshots of running TUI applications, even in headless CI environments like Xvfb, Sway, or kwin.
  • Flow Execution Engine: Execute pre-defined flows (YAML) against terminal instances. Great for integration testing or guiding autonomous agent tasks.
  • Cross-Platform: Built to support macOS, Linux, and Windows natively. Works with standard terminals (Terminal.app, iTerm2, Gnome Terminal, Windows Terminal) and modern GPU-accelerated emulators (Alacritty, WezTerm, Ghostty, Kitty).

Use Cases

Automated CLI/TUI Testing

Run end-to-end tests for your CLI tools or TUI applications. mcp-tuikit launches each app in its own session, interacts via emulated keystrokes, and verifies results through text or visual PNG screenshots.

AI-Driven Terminal Automation

Let AI agents like Claude Code autonomously operate complex terminal environments. The agent can spawn vim, send j, k keystrokes, wait for UI updates, and read the screen state, creating a complete feedback loop.

Headless CI Integration

Integrate terminal GUI testing into CI/CD pipelines. mcp-tuikit supports xterm.js via Playwright, or Linux native headless servers (Sway, kwin, Xvfb), making it perfect for GitHub Actions or GitLab CI.

Available Tools

ToolParametersDescription
create_sessioncommand, cols?, rows?Create a new terminal session running a specific command.
close_sessionsession_idClose an active terminal session.
create_snapshotsession_id, format (txt/png/both), intent?Capture a txt and/or png snapshot from an active session.
send_keyssession_id, keys, submit? (bool)Send keystrokes to an active session using tmux format.
wait_for_textsession_id, pattern, timeout_ms?Wait for a regex pattern to appear in the terminal output.
run_flowyaml_path?, yaml_string?, cols?, rows?Run a TUI YAML flow and capture artifacts autonomously.
list_sessions(none)List all active terminal sessions and their states.
check_system_dependencies(none)Check if the host system has all required dependencies.

Resources:

  • terminal://session/{id}/screen.txt?maxLines={limit}: Read the raw plaintext buffer of the active terminal session.

How It Works

flowchart TD
    Agent["AI Agent (Claude, Cursor)"] <-->|MCP Protocol| Server["mcp-tuikit Server"]

    Server --> |create_session| TMUX["tmux Session"]
    Server --> |send_keys| TMUX
    Server --> |create_snapshot (txt)| TMUX

    TMUX --> |Spawns via Backend| Emulator["Terminal Emulator / Headless Engine"]

    Emulator --> |Alacritty/WezTerm/etc| Native["Native OS Window"]
    Emulator --> |xterm.js| Playwright["Headless Browser"]
    Emulator --> |Xvfb/Sway/kwin| LinuxHeadless["Linux Headless Compositor"]

    Server --> |create_snapshot (png)| ScreenCapture["Sharp / osascript / grim / Playwright"]