ht-mcp

Rust License: Apache 2.0

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

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

ht-mcp is useful for enabling Agents to use terminals (e.g. bash, zsh, fish) in the same way a human does.

It solves the challenge of agents stalling when they encounter interactive terminal commands.

Related MCP Servers

Lilith Shell
charles-adedotun
-
security
A
license
-
quality
An enhanced MCP server that grants AI assistants the ability to execute terminal commands on a user's system with improved security controls, designed for use in controlled environments.
Last updated -
MIT License
MCP Shell Server
mkusaka
A
security
A
license
A
quality
A server that uses the Model Context Protocol (MCP) to allow AI agents to safely execute shell commands on a host system.
Last updated -
1
44
6
MIT License
PyMCPAutoGUI
kitfactory
-
security
A
license
-
quality
An MCP server that bridges AI agents with GUI automation capabilities, allowing them to control mouse, keyboard, windows, and take screenshots to interact with desktop applications.
Last updated -
10
MIT License
Hyperliquid MCP Server
-
security
-
license
-
quality
A comprehensive MCP server that provides a complete wrapper around the Hyperliquid SDK, enabling AI assistants to interact with both spot and futures markets for retrieving data, executing trades, and managing positions.

View all related MCP servers

HT-MCP