🚀 ht-mcp

A high-performance Rust implementation of a Model Context Protocol (MCP) server for headless terminal ht.

🚀 Quick Start

ht-mcp is a high - performance MCP server implemented in Rust. You can quickly start using it by following the installation steps below.

✨ Features

• 🚀 Pure Rust: Single binary MCP server, no external dependencies
• 🔗 Direct Integration: Embed excellent ht headless terminal library for optimal performance
• 🖥️ Multi - Session: Concurrent terminal session management
• 🌐 Web Interface: Optional live terminal preview

📸 Demo

ht - mcp in Memex


ht - mcp in [Claude Code](https://www.anthropic.com/claude - code)


📦 Installation

🍺 Homebrew (Recommended)

brew tap memextech/tap
brew install ht - mcp

📦 Pre - built Binaries

Download from [releases](https://github.com/memextech/ht - mcp/releases/latest):

# 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

# From crates.io (stable)
cargo install ht - mcp

# From git (latest)
cargo install --git https://github.com/memextech/ht - mcp

🔧 Build from Source

git clone https://github.com/memextech/ht - mcp.git
cd ht - mcp
git submodule update --init --recursive
cargo install --path .

See docs/INSTALLATION.md for detailed installation options.

🛠️ MCP Tools

⚠️ Important Note

Parameters use camelCase (e.g., sessionId, enableWebServer) for MCP compatibility.

⚙️ Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "ht - mcp": {
      "command": "ht - mcp",
      "args": ["--debug"]
    }
  }
}

For custom installation paths:

{
  "mcpServers": {
    "ht - mcp": {
      "command": "/path/to/ht - mcp",
      "args": []
    }
  }
}

💻 Usage Examples

Basic Usage

# 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:

# 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

# 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)
• Supported OS: Linux, macOS, Windows (experimental)

🛠️ Development

# 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 for details.

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

Built with Memex✨

Fixed submodule commit reference