textual-docs-mcp 0.1.0

MCP server providing AI agents with Textual TUI library documentation, examples, and best practices

textual-docs-mcp

An MCP server for Textual TUI framework documentation, code examples, widget references, and best practices.

✅ What You Get

This MCP server gives AI agents instant access to:

• Full-text BM25 search across all Textual documentation, guides, and examples
• Widget documentation — complete reference for every built-in widget
• Guide retrieval — layout, events, reactivity, CSS, workers, screens, and more
• Code examples — real, runnable Python examples covering common Textual patterns
• Topic catalogues — browse all available guides and widgets

All documentation is bundled inside the package — no external API calls, no network requests, no rate limits.

Installation

pip (recommended)

pip install textual-docs-mcp

From Source

git clone https://github.com/diaz3618/textual-docs-mcp.git
cd textual-docs-mcp
pip install -e ".[dev]"

Docker

docker pull ghcr.io/diaz3618/textual-docs-mcp:latest

Or build locally:

docker build -t textual-docs-mcp .

Usage

Stdio Transport (MCP Clients)

textual-docs-mcp
# or
python -m textual_docs_mcp

Docker

docker run -i textual-docs-mcp

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "textual-docs": {
      "command": "textual-docs-mcp"
    }
  }
}

Claude Code

claude mcp add --scope user textual-docs -- textual-docs-mcp

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "textual-docs": {
      "type": "stdio",
      "command": "textual-docs-mcp"
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "textual-docs": {
      "command": "textual-docs-mcp"
    }
  }
}

Docker with MCP Client

{
  "mcpServers": {
    "textual-docs": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/diaz3618/textual-docs-mcp:latest"]
    }
  }
}

More client configurations →

Available Tools

Tool	Description
search_textual_docs_tool	BM25 full-text search across all docs, guides, and examples
get_guide_tool	Fetch a specific Textual guide (layout, events, reactivity, ...)
get_widget_docs_tool	Fetch complete docs for a specific widget
get_code_examples_tool	Fetch runnable code examples for a topic
list_guides_tool	Catalogue of all available guides and how-to articles
list_widgets_tool	Catalogue of all available widget documentation
get_textual_overview_tool	High-level introduction to the Textual framework

Development

# Install with dev dependencies
make dev

# Run tests
make test

# Run all checks (lint, typecheck, deadcode)
make check

# Build Docker image
make docker-build

# Rebuild documentation bundle (requires Textual source)
TEXTUAL_REPO_PATH=/path/to/textual make bundle

See make help for all available targets.

More Documentation

• Client Configuration — Setup for 8+ MCP clients
• Architecture — Module design, data flow, bundle format

License

MIT