mcp server for unix pty control
About
The native MCP server for Unix PTY control gives AI models authentic, low-latency terminal access by spawning true pseudo-terminals—not brittle AppleScript hacks—so you can open persistent Bash, Python, or SSH sessions, run commands like “ssh prod.server,” and stream only fresh o
Details
- Author
- ianks
- Downloads
- 506
- Categories
- Developer Tools
Jump to
- True Unix ptys, not AppleScript or workarounds
- Async I/O powered by Tokio
- Smart buffering that only returns new output
- Session persistence across tool calls
- Multi-session support to run several terminals at once
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
mcp server for unix pty controlCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install with cargo install --git https://github.com/ianks/terminal-mcp, then add to Claude Code using claude mcp add --scope user terminal-mcp. AI models can then call tools like create_session, execute_command, and list_sessions via JSON-RPC.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcp server for unix pty control": {
"terminal-mcp": {
"type": "stdio",
"command": "terminal-mcp"
}
}
}
}McpServers
{
"terminal-mcp": {
"type": "stdio",
"command": "terminal-mcp"
}
}terminal-mcp
> native mcp server for unix pty control.
what
mcp server that gives ai models real terminal access. spawn sessions, run commands, read output. that's it.
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_session",
"arguments": {
"session_name": "prod-debug",
"command": "ssh prod.server"
}
}
}
features
- true ptys not applescript hacks, real unix terminals
- async everything tokio-powered non-blocking i/o
- smart buffering only new output, no duplicates
- session persistence terminals stay alive between calls
- multi-session support run multiple terminals at once and switch between them
concepts
- sessions: named terminal instances (bash, python, ssh)
- tools: mcp protocol endpoints the ai calls
- ptys: pseudo-terminals for proper shell interaction
- managers: lifecycle and cleanup automation
tools
- create_session: spawn a new terminal
- execute_command: run and get output immediately
- execute_command_async: start long-running commands
- read_streaming_output: poll async command progress
- list_sessions: see what's running
- destroy_session: cleanup when done
- send_control_character: ctrl-c and friends
config
claude code:
cargo install --git https://github.com/ianks/terminal-mcp
claude mcp add --scope user terminal-mcp
dev
cargo test -- --nocapture # see test output
RUST_LOG=debug cargo run # verbose logging
cargo clippy # lint
cargo fmt # format
architecture
mcp api layer (json-rpc)
↓
session manager (lifecycle)
↓
pty engine (pty-process)
↓
unix ptys (kernel)
philosophy
> ai can interact with computers like humans do.
> no abstractions. just shells.
license
mit
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
