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.
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
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
success flag plus typed fields (screen, outcome, passed, row/col,
screen_excerpt on failed assertions, error when something broke). Agents and
scripts branch on fields instead of parsing ✓/✗ strings.
The current screen is also exposed as an MCP resource at
tui://{session_id}/screen.
TuiHandle offers send, send_ctrl, expect, assert_contains, assert_at,
wait_until_contains, screen, line, and cursor; failures raise
AssertionError with the current screen attached. Sessions are closed at test
teardown, pass or fail.
Auto-detection: Tools automatically use appropriate mode based on session
Limitations
Currently designed for Unix-like systems (Linux, macOS)
Windows support may require modifications (consider using winpty or similar)
Mouse support in TUIs is not currently available
Buffer mode requires slightly more memory for screen emulation
Position-based assertions only work in buffer mode
Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
License
MIT License - see LICENSE file for details
Related tools
docs/landscape.md surveys the other TUI-testing tools,
what each is built on, the core ideas in each, and which of those ideas this
project has or could adopt. The tools covered:
microsoft/tui-test — Rust engine with Alacritty, Ghostty, Rio and xterm.js backends; Playwright-style locators; CLI plus Rust, Python, JS and Go bindings
antithesishq/bombadil — property-based exploration of web and terminal UIs on portable-pty and libghostty-vt, with temporal properties and trace shrinking
testty — Rust; semantic recipes over styles, scenarios compiled to VHS tapes
hegner123/tui-test-ghost and mjpowersjr/vterm-mcp — MCP servers on libghostty-vt, the closest in shape to this project; tui-test-ghost records tool calls to JSONL and replays them as tests
For a build you can open directly from disk with local search, use
MKDOCS_OFFLINE=true .venv-docs/bin/mkdocs build --strict --site-dir /tmp/mcp-tui-test-offline.
Offline builds use .html page URLs; normal builds retain the published directory URLs.
M
MCP Tui Test
GeorgePearse·19 estrelas·
MCP server for testing Terminal User Interfaces - like Playwright for TUI applications
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo MCP Tui Test?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
MCP Tui Test precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte MCP Tui Test usa?
MCP Tui Test roda localmente via stdio.
Quando MCP Tui Test foi verificado pela última vez?
Última verificação: 2026-10-28. MCP server for testing Terminal User Interfaces - like Playwright for TUI applications