MCP TUI Test

Like Playwright, but for Terminal User Interfaces

An MCP (Model Context Protocol) server that enables AI assistants to test Terminal User Interface (TUI) applications. This server provides tools to launch, interact with, and verify TUI applications programmatically.

📚 View Documentation

Features

• Dual Testing Modes: Choose between stream mode (for CLI tools) or buffer mode (for full TUIs with position awareness)
• Launch TUI Applications: Start any terminal-based application with configurable dimensions
• Send Keyboard Input: Simulate user typing, special keys, and control combinations
• Capture Screen Output: Read and analyze the current terminal display
• Position-Based Testing: Verify text at specific screen coordinates (buffer mode)
• Cursor Tracking: Monitor cursor position in real-time (buffer mode)
• Wait for Text: Asynchronously wait for specific content to appear
• Assertions: Verify that expected content is present in the output
• Session Management: Run multiple TUI applications simultaneously

Testing Modes

Stream Mode (Default)

• Best for: CLI tools, command-line applications, simple interactive programs
• Uses: pexpect for stream-based testing
• Features: Text matching, pattern waiting, output capture
• Example use cases: git, npm, grep, interactive shell scripts

Buffer Mode

• Best for: Full TUI applications, ncurses apps, dialog boxes, menus
• Uses: pexpect + pyte for screen buffer emulation
• Features: All stream features PLUS position-based assertions, cursor tracking, region extraction
• Example use cases: htop, vim, dialog, interactive menus

When to use which mode:

• Use stream mode for applications that output text sequentially
• Use buffer mode for applications that draw complex UIs with cursor movement

Installation

Prerequisites

• Python 3.10 or higher
• uv

Install

Once published to PyPI, no install is needed — run it straight from uvx:

uvx mcp-tui-test

For development:

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Go implementation

A sibling Go implementation lives in go/ — the same tool contract (same tool names, same structured result shapes, same tui://{session_id}/screen resource), as a single static binary with zero runtime dependencies:

go install github.com/GeorgePearse/mcp-tui-test/go/cmd/mcp-tui-test@latest

{
  "mcpServers": {
    "tui-test": { "command": "mcp-tui-test" }
  }
}

Built on the official Go MCP SDK, creack/pty, and vt10x for buffer-mode screen emulation. The Python package remains the home of the pytest plugin; the two share the tool schema, so clients can’t tell them apart.

Structured results

Every tool returns structured content (with an output schema), not prose: a