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