ht-mcp

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

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

Installation

🍺 Homebrew (Recommended)

brew tap memextech/tap
brew install ht-mcp

📦 Pre-built Binaries

Download from releases:

# 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

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:

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

For custom installation paths:

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

Usage Example

# Start the MCP server
ht-mcp

# With debug logging
ht-mcp --debug

Once configured in your MCP client:

Create session: ht_create_session → Returns session ID
Run commands: ht_execute_command with session ID and command
Interactive input: ht_send_keys for multi-step interactions
Check state: ht_take_snapshot to see current terminal
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:

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

See LICENSE for details.

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

Built with Memex✨

Fixed submodule commit reference

Headless Terminal