MCPretentious

npm version Test Status License: MIT

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

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

Feature	iTerm2	TMux
Platform	macOS	Cross-platform
Method	WebSocket + Protobuf	Direct commands
Performance	Fastest	Fast
Colors	Full RGB	ANSI 256
Authentication	Cookie/key	Unix permissions

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 [email protected]