Textual MCP Server
MCP server for programmatically driving Textual TUI apps headlessly
Installation
npx textual-mcp-serverAsk AI about Textual MCP Server
Powered by Claude Β· Grounded in docs
I know everything about Textual MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
textual-mcp-server
An MCP server that lets AI agents launch, interact with, and inspect Textual TUI applications headlessly. Drive any Textual app through its full lifecycle β click buttons, type text, read widget state, take screenshots β all via the Model Context Protocol.
Features
- Headless app execution β Launch any Textual app without a terminal, powered by Textual's built-in
Pilottesting API - Full interaction toolkit β Click, type, press keys, and hover over widgets using CSS selectors
- Rich state inspection β Snapshot the widget tree, query widgets by selector, and extract type-specific properties from 16+ widget types
- Multi-session support β Run multiple apps concurrently with isolated sessions
- Error tracking β Automatic collection of worker errors and app exceptions via message hooks
- Screenshot capture β Export the current screen as plain text or SVG
Installation
Requires Python 3.10+.
pip install textual-mcp-server
For development:
git clone https://github.com/discohead/textual-mcp-server.git
cd textual-mcp-server
pip install -e ".[dev]"
Quick Start
As a standalone server
textual-mcp
With Claude Code
claude mcp add textual -- textual-mcp
Or add manually to your MCP configuration (e.g., ~/.claude.json or project .mcp.json):
{
"mcpServers": {
"textual": {
"command": "textual-mcp"
}
}
}
Typical workflow
1. textual_launch("my_app.py") β session_id
2. textual_snapshot(session_id) β widget tree + focus + bindings
3. textual_click(session_id, "#submit") β interact
4. textual_screenshot(session_id) β visual output
5. textual_stop(session_id) β cleanup
Tools
Lifecycle
| Tool | Description |
|---|---|
textual_launch | Launch a Textual app headlessly. Accepts a file path (app.py), path with class (app.py:MyApp), or module path (mypackage.module:MyApp). Returns a session_id. |
textual_stop | Stop a running session and return any collected errors. |
Interaction
| Tool | Description |
|---|---|
textual_press | Simulate key presses (e.g., ["enter"], ["ctrl+s"]). |
textual_click | Click a widget by CSS selector with optional offset and repeat count. |
textual_type_text | Type text into the focused input widget, with optional submit (Enter). |
textual_hover | Hover the mouse over a widget by CSS selector. |
Observation
| Tool | Description |
|---|---|
textual_snapshot | Snapshot the widget tree with ref markers, focus state, active key bindings, and errors. |
textual_screenshot | Capture the current screen as plain text or SVG. |
textual_query | Query widgets matching a CSS selector. Returns type, ID, classes, and extracted properties. |
textual_get_screen_stack | Get the current screen stack with modal indicators. |
Assertion & Waiting
| Tool | Description |
|---|---|
textual_wait_for | Wait for a condition: idle, animation, workers (all complete), or widget (selector appears). |
textual_check_errors | Check for collected worker errors and app exceptions. |
Architecture
textual_mcp/
βββ server.py # FastMCP server, tool registration, and tool implementations
βββ session.py # AppSession β headless app lifecycle via Pilot
βββ session_manager.py # Multi-session management
βββ app_loader.py # Dynamic app loading from file or module path
βββ error_collector.py # Message hook for worker error aggregation
βββ serializers/
βββ widget_tree.py # DOM β indented text tree with [ref=N] markers
βββ widget_state.py # Type-specific property extraction (16 widget types)
Key design decisions:
AppSessionwraps Textual'sApp.run_test()to provide launch/stop semantics with a persistentPilothandleWidgetTreeSerializerproduces LLM-friendly text output β interactive widgets get[ref=N]markers; scrollbars and hidden widgets are excludedWidgetStateExtractoruses an ordered isinstance registry to extract properties from Input, Button, DataTable, TextArea, Tree, and 11 other widget typesErrorCollectorhooks into Textual's message system to captureWorker.StateChangederrors without disrupting normal operation
Supported Widget Types
The state extractor provides rich property data for:
Input, Button, Static, Label, Checkbox, Switch, Select, TextArea, DataTable, Tree, ListView, OptionList, TabbedContent, ProgressBar, RadioSet, ContentSwitcher
Development
# Run tests
pytest
# Run a specific test
pytest tests/test_integration_calculator.py -v
Requirements
License
MIT
