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