HT-MCP

# ht-mcp [](https://www.rust-lang.org) [](https://opensource.org/licenses/Apache-2.0) A high-performance Rust implementation of a Model Context Protocol (MCP) server for headless terminal [ht](https://github.com/andyk/ht). ## Features - 🚀 **Pure Rust**: Single binary MCP server, no external dependencies - 🔗 **Direct Integration**: Embed excellent [ht](https://github.com/andyk/ht) headless terminal library for optimal performance - 🖥️ **Multi-Session**: Concurrent terminal session management - 🌐 **Web Interface**: Optional live terminal preview ## Demo ### ht-mcp in [Memex](https://memex.tech)  ### ht-mcp in [Claude Code](https://www.anthropic.com/claude-code)  ## Installation ### 🍺 Homebrew (Recommended) ```bash brew tap memextech/tap brew install ht-mcp ``` ### 📦 Pre-built Binaries Download from [releases](https://github.com/memextech/ht-mcp/releases/latest): ```bash # macOS Intel curl -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-x86_64-apple-darwin -o ht-mcp # macOS Apple Silicon curl -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-aarch64-apple-darwin -o ht-mcp # Linux curl -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-x86_64-unknown-linux-gnu -o ht-mcp # Windows (PowerShell) curl.exe -L https://github.com/memextech/ht-mcp/releases/latest/download/ht-mcp-x86_64-pc-windows-msvc -o ht-mcp.exe # Make executable and install chmod +x ht-mcp && sudo mv ht-mcp /usr/local/bin/ ``` ### 🦀 Cargo ```bash # From crates.io (stable) cargo install ht-mcp # From git (latest) cargo install --git https://github.com/memextech/ht-mcp ``` ### 🔧 Build from Source ```bash git clone https://github.com/memextech/ht-mcp.git cd ht-mcp git submodule update --init --recursive cargo install --path . ``` See [docs/INSTALLATION.md](docs/INSTALLATION.md) for detailed installation options. ## MCP Tools | Tool | Description | Parameters | |------|-------------|------------| | `ht_create_session` | Create new terminal session | `command?`, `enableWebServer?` | | `ht_send_keys` | Send keystrokes to session | `sessionId`, `keys[]` | | `ht_take_snapshot` | Capture terminal state | `sessionId` | | `ht_execute_command` | Execute command and get output | `sessionId`, `command` | | `ht_list_sessions` | List all active sessions | None | | `ht_close_session` | Close terminal session | `sessionId` | > **Note**: Parameters use camelCase (e.g., `sessionId`, `enableWebServer`) for MCP compatibility. ## Configuration Add to your MCP client configuration: ```json { "mcpServers": { "ht-mcp": { "command": "ht-mcp", "args": ["--debug"] } } } ``` For custom installation paths: ```json { "mcpServers": { "ht-mcp": { "command": "/path/to/ht-mcp", "args": [] } } } ``` ## Usage Example ```bash # Start the MCP server ht-mcp # With debug logging ht-mcp --debug ``` Once configured in your MCP client: 1. **Create session**: `ht_create_session` → Returns session ID 2. **Run commands**: `ht_execute_command` with session ID and command 3. **Interactive input**: `ht_send_keys` for multi-step interactions 4. **Check state**: `ht_take_snapshot` to see current terminal 5. **Clean up**: `ht_close_session` when finished ## Response Format This server returns **human-readable text responses** (not JSON), designed for natural language interaction: ```text # Create session response HT session created successfully! Session ID: abc123-def456-789... 🌐 Web server enabled! View live terminal at: http://127.0.0.1:3618 ``` ```text # Terminal snapshot response Terminal Snapshot (Session: abc123...) bash-3.2$ ls -la total 16 drwxr-xr-x 4 user staff 128 Jun 13 10:30 . -rw-r--r-- 1 user staff 45 Jun 13 10:30 file.txt bash-3.2$ ``` ## Requirements - **Rust**: 1.75+ (install via [rustup](https://rustup.rs/)) - **Supported OS**: Linux, macOS, Windows (experimental) ## Development ```bash # Clone with submodules git clone --recursive https://github.com/memextech/ht-mcp.git cd ht-mcp # Build cargo build # Run cargo run # Test cargo test ``` ## Troubleshooting **Installation Issues:** - Ensure Rust 1.75+ is installed - Check internet connection for git submodules - Verify `~/.cargo/bin` is in PATH **Runtime Issues:** - Use `ht-mcp --debug` for verbose logging - Check MCP client configuration syntax - Verify binary path: `which ht-mcp` ## Performance Compared to the original [TypeScript implementation](https://github.com/memextech/headless-terminal-mcp): - **40x faster startup** (~50ms vs ~2s) - **70% less memory** (~15MB vs ~50MB) - **Single binary** (4.7MB vs ~200MB Node.js) - **Zero subprocess overhead** ## License Apache 2.0 License Copyright (c) 2025 Atlas Futures Inc. See [LICENSE](LICENSE) for details. ## Contributing Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. --- Built with [Memex](https://memex.tech)✨ # Fixed submodule commit reference