terminal-mcp

ianks/terminal-mcp

3.4

If you are the rightful owner of terminal-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The terminal-mcp is a native MCP server designed for Unix pty control, enabling AI models to interact with real terminal environments.

Tools
7
Resources
0
Prompts
0

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