JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 11
  • Score
    100M100P100Q51246F
  • License MIT

MCPretentious - Universal Terminal MCP. High-performance terminal automation for iTerm2 (WebSocket) and tmux (control mode). Cross-platform support with cursor position, colors, and layered screenshots.

Package Exports

  • mcpretentious
  • mcpretentious/mcpretentious.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (mcpretentious) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

MCPretentious - Universal Terminal MCP

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

License

MIT - Tobias Oetiker tobi@oetiker.ch