MCPretentious - Universal Terminal MCP

MCP server for terminal control. Supports iTerm2 (macOS) via WebSocket API and tmux (cross-platform) via direct commands.

📋 Latest Release (v1.3.0 - 2025-09-03)

Added

• Alt key support - Comprehensive Alt key combinations for mcpretentious-type tool

  • Alt + Letters (a-z): alt-a through alt-z

  • Alt + Shift + Letters: alt-shift-a through alt-shift-z for uppercase

  • Alt + Numbers (0-9): alt-0 through alt-9

  • Alt + Navigation keys: arrow keys, home, end, pageup, pagedown

  • Alt + Function keys (F1-F12): alt-f1 through alt-f12

  • Alt + Special keys: tab, enter, space, backspace

  • Uses standard terminal escape sequences (ESC prefix and CSI modifiers)

For full changelog, see CHANGELOG.md

Related MCP server: poof-mcp

Installation

npm install -g mcpretentious

Prerequisites

iTerm2 (macOS):

• Enable Python API: iTerm2 → Preferences → General → Magic → Enable "Python API"

TMux (any platform):

• Install tmux: brew install tmux / apt install tmux / etc.

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcpretentious": {
      "command": "npx",
      "args": ["mcpretentious"]
    }
  }
}

Claude Code

claude mcp add mcpretentious npx mcpretentious

Main Applications

• TUI application testing: Simulates all human interactions - keyboard, mouse, screen reading

• Remote server management: Persistent terminal sessions allow remote system control over SSH

Features

• Multiple backends: iTerm2 (WebSocket, 20x faster than AppleScript) and tmux (direct commands)

• No focus stealing: Background terminal control

• Real terminal IDs: Access existing terminals, not just MCP-created ones

• Screen reading: Actual viewport content with cursor position and colors

• Mouse support: Full SGR protocol (click, drag, scroll) in both backends

• Token-optimized screenshots: 85-98% reduction via layered format

Backend Comparison

Tools

• mcpretentious-open - Create terminal session

• mcpretentious-type - Send text/keys/ASCII codes

• mcpretentious-screenshot - Get screen content (configurable layers)

• mcpretentious-mouse - Send mouse events (SGR protocol)

• mcpretentious-resize - Set terminal dimensions

• mcpretentious-close - Close terminal

• mcpretentious-list - List active terminals

Testing

npx mcpretentious-test          # Basic test
npx mcpretentious-test --verbose # Detailed output

Security

Full terminal access - the LLM can run any command you could. Be cautious with:

• Untrusted commands

• System passwords

• Destructive operations

Documentation

• API Documentation

• Changelog

License

MIT - Tobias Oetiker tobi@oetiker.ch