RS

ht-mcp

by memextech/ht-mcp

0 views

Pure Rust implementation of MCP server for headless terminal

rustintegrationSystem Monitoring

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 Memex

ht-mcp in Claude Code

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

ToolDescriptionParameters
ht_create_sessionCreate new terminal sessioncommand?, enableWebServer?
ht_send_keysSend keystrokes to sessionsessionId, keys[]
ht_take_snapshotCapture terminal statesessionId
ht_execute_commandExecute command and get outputsessionId, command
ht_list_sessionsList all active sessionsNone
ht_close_sessionClose terminal sessionsessionId

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:

  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:

  • 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

Install

{
  "mcpServers": {
    "ht-mcp": {
      "command": "ht-mcp",
      "args": [
        "--debug"
      ]
    }
  }
}
For more configuration details, refer to the content on the left

Related

Related projects feature coming soon

Will recommend related projects based on sub-categories