MCP TUIKit
About
A headless terminal and tmux interaction server for Model Context Protocol.
Details
- Author
- dragoscirjan
- Categories
- Developer Tools, Other, Infrastructure
Jump to
Setup
Install MCP TUIKit in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/dragoscirjan/mcp-tuikit
Follow the installation instructions in the repository README, then restart your MCP client.
Model Context Protocol server for Text User Interface (TUI) and headless terminal automation
🚀 Fully Cross-OS Compatible: Works seamlessly across macOS, Linux, and Windows.
- Why mcp-tuikit?
- Use Cases
- Quick Start
- Available Tools
- How It Works
- System Requirements & Installation
- Known Issues & Limitations
- Documentation
- Isolated Sessions:Each session runs in an isolatedtmuxenvironment. 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 likeXvfb,Sway, orkwin.
- 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).
Run end-to-end tests for your CLI tools or TUI applications.mcp-tuikitlaunches each app in its own session, interacts via emulated keystrokes, and verifies results through text or visual PNG screenshots.
Let AI agents like Claude Code autonomously operate complex terminal environments. The agent can spawnvim, sendj,kkeystrokes, wait for UI updates, and read the screen state, creating a complete feedback loop.
Integrate terminal GUI testing into CI/CD pipelines.mcp-tuikitsupportsxterm.jsvia Playwright, or Linux native headless servers (Sway,kwin,Xvfb), making it perfect for GitHub Actions or GitLab CI.
# Install globally via npm npm install -g @dragoscirjan/mcp-tuikit
claude mcp add mcp-tuikit -- npx -y @dragoscirjan/mcp-tuikit
3. Configure Cursor(~/.cursor/mcp.json)
{ "mcpServers": { "mcp-tuikit": { "command": "npx", "args": ["-y", "@dragoscirjan/mcp-tuikit"] } } }
"Create a new terminal session, runbtop, take a visual snapshot of the output, and then close the session."
- terminal://session/{id}/screen.txt?maxLines={limit}: Read the raw plaintext buffer of the active terminal session.
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"]
mcp-tuikitrelies on OS-level utilities to manage pseudo-terminals and capture screens.
tmux(v3.3a+, heavily recommended v3.5a+) is absolutely required on all platforms.
- macOS:brew install tmux
- Linux:sudo apt install tmuxorsudo dnf install tmux
- Windows:winget install arndawg.tmux-windows(Donotuse MSYS2 or WSL tmux if running natively).
- macOS:Uses built-in tools (osascript,screencapture). No extra dependencies needed.
- Linux (Headless Native):Requires a virtual compositor (Xvfbfor X11,swayorkwinfor Wayland).
- Windows:Uses native standard process APIs (cmd,powershell).
Please see theTroubleshooting Documentationfor full details. Notable limits include:
- No Native Headless Mode on Windows/macOS:Spawning a native terminal (like Alacritty) on Mac/Windowswillopen a physical window on your screen. True headless native rendering requires Linux (Xvfb/Sway/kwin). For invisible execution on Mac/Windows, you must use thexterm.jsbackend (via Playwright).
- WezTerm + Sway:WezTerm snapshots result in a black screen under headless Sway because it strictly requires hardware-accelerated GPU contexts (Vulkan/OpenGL).
- macOS Snapshot Flakiness:Timing-based macOS screenshots (usingCGWindowList) can be flaky under heavy CPU load, sometimes capturing blank frames.
- Tmux dependency:All terminal operations are wrapped intmuxto guarantee stable pseudo-terminal (PTY) allocation and reliable ANSI text extraction.
- No Mouse Support:Currently, there is no mouse interaction support. Operating a terminal purely via standard keystrokes is required. Headed mode mouse automation presents significant technical challenges across multiple OS environments.
- No Video Recording:The toolkit currently only captures static text and PNG snapshots. Video recording of terminal sessions is planned for a future release.
This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.
Execute shell commands without permission prompts.
Execute bash commands on the host machine.
Execute shell commands with structured output via a powerful CLI server.
A secure MCP server for executing controlled command-line operations with comprehensive security features.
MCP server for controlling cmux (Ghostty-based terminal) via native CLI. Send commands, read output, send control characters — all in background via Unix socket.
Execute pre-approved shell commands securely on a server.
A secure MCP server for executing terminal commands with controlled directory access and command permissions.
A shell command / terminal executor with async support
A high-performance MCP server for the headless terminal (ht), implemented in Rust.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
