Skip to main content
Glama
MCPretentious

MCPretentious

by oetiker

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

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

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

Available Tools

9 tools
mcpretentious-closeB

Closes the terminal window associated with the specified terminal ID.

Inputs: terminalId (required).

mcpretentious-infoA

Gets terminal metadata including dimensions (columns × rows) and session information.

Inputs: terminalId (required).

mcpretentious-listA

Lists all currently open terminal sessions with their IDs.

Inputs: no named parameters.

mcpretentious-mouseA

Send mouse events to a terminal using SGR mouse protocol.

This tool provides direct control over mouse events following the terminal's SGR (Select Graphic Rendition) mouse protocol.

EVENTS:
- 'press': Mouse button press event
- 'release': Mouse button release event  
- 'drag': Mouse movement with button held down

BUTTONS (use names or button-N format):
Named buttons:
- 'left': Left mouse button
- 'middle': Middle mouse button
- 'right': Right mouse button
- 'scrollUp': Scroll wheel up
- 'scrollDown': Scroll wheel down

Direct button codes:
- 'button-0' through 'button-127': Direct SGR button codes
- Common codes: 0=left, 1=middle, 2=right, 64=scrollUp, 65=scrollDown

MODIFIERS (optional, default to false):
- shift: Hold shift key during event
- alt: Hold alt/option key during event
- ctrl: Hold control key during event

COORDINATES:
- x and y are 0-based character positions (column, row)
- The protocol will convert to 1-based coordinates internally

EXAMPLES:
- Left click at (10,5): event='press', button='left', x=10, y=5, then event='release' with same coordinates
- Drag from (5,5) to (15,10): event='press' at (5,5), event='drag' at (15,10), event='release' at (15,10)
- Scroll up at (20,8): event='press', button='scrollUp', x=20, y=8 (no release needed for scroll)

Inputs: terminalId (required), event (required), x (required), y (required), +4 more.

mcpretentious-openA

Opens a new terminal window and creates a tracked terminal session. Returns a terminal ID that can be used with other commands.

Inputs: columns, rows.

mcpretentious-readA

Reads text output from a terminal session. Returns the current screen contents. Use mcpretentious-screenshot for rich terminal info including colors, cursor position, and styles.

Inputs: terminalId (required), lines.

mcpretentious-resizeB

Resizes a terminal to the specified dimensions in columns × rows.

Inputs: terminalId (required), columns (required), rows (required).

mcpretentious-screenshotA

Takes a token-optimized screenshot of the terminal screen using a layered format that reduces token usage by 85-98%. Returns only the data layers you need (text, cursor, colors, styles). Supports viewport limiting to show just a region or area around cursor. Essential for inspecting TUI applications without hitting token limits.

Inputs: terminalId (required), layers, region, aroundCursor, +1 more.

mcpretentious-typeA

Send text and keystrokes to a terminal. Always pass as array.

Examples: ["ls -la"], ["cd /path", {"key": "enter"}], ["Hello", 32, "World"], [{"key": "ctrl-c"}]

Supported keys: tab, shift-tab, enter, return, escape, esc, backspace, delete, up, down, right, left, home, end, pageup, pagedown, ctrl-a, ctrl-b, ctrl-c, ctrl-d, ctrl-e, ctrl-f, ctrl-g, ctrl-h, ctrl-i, ctrl-j, ctrl-k, ctrl-l, ctrl-m, ctrl-n, ctrl-o, ctrl-p, ctrl-q, ctrl-r, ctrl-s, ctrl-t, ctrl-u, ctrl-v, ctrl-w, ctrl-x, ctrl-y, ctrl-z, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12, alt-a, alt-b, alt-c, alt-d, alt-e, alt-f, alt-g, alt-h, alt-i, alt-j, alt-k, alt-l, alt-m, alt-n, alt-o, alt-p, alt-q, alt-r, alt-s, alt-t, alt-u, alt-v, alt-w, alt-x, alt-y, alt-z, alt-shift-a, alt-shift-b, alt-shift-c, alt-shift-d, alt-shift-e, alt-shift-f, alt-shift-g, alt-shift-h, alt-shift-i, alt-shift-j, alt-shift-k, alt-shift-l, alt-shift-m, alt-shift-n, alt-shift-o, alt-shift-p, alt-shift-q, alt-shift-r, alt-shift-s, alt-shift-t, alt-shift-u, alt-shift-v, alt-shift-w, alt-shift-x, alt-shift-y, alt-shift-z, alt-0, alt-1, alt-2, alt-3, alt-4, alt-5, alt-6, alt-7, alt-8, alt-9, alt-tab, alt-enter, alt-space, alt-backspace, alt-left, alt-right, alt-up, alt-down, alt-home, alt-end, alt-pageup, alt-pagedown, alt-f1, alt-f2, alt-f3, alt-f4, alt-f5, alt-f6, alt-f7, alt-f8, alt-f9, alt-f10, alt-f11, alt-f12

Inputs: terminalId (required), input (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct action: close, info, list, mouse, open, read, resize, screenshot, type. There is no functional overlap; an agent can clearly distinguish between them.

    Naming Consistency4/5

    Most tools use an imperative verb form (close, open, list, type, read, resize), but 'mcpretentious-mouse' is a noun rather than a verb, and 'info' is also a noun. This minor inconsistency prevents a top score.

    Tool Count5/5

    With 9 tools covering open, close, list, info, type, read, resize, screenshot, and mouse input, the count is well-scoped for terminal session management. No tool feels redundant or missing.

    Completeness5/5

    The tool set covers the full lifecycle of terminal sessions: creation, destruction, listing, input (keyboard and mouse), output reading (plain and styled), resizing, and metadata retrieval. No obvious gaps for typical use.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI agents to control the macOS Terminal.app using AppleScript and the zmx session manager. It allows agents to send keystrokes, type text, and capture screen output in real-time.
      -
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to control iTerm2 sessions, windows, tabs, and profiles using the official iTerm2 Python API. It includes a security model with session tagging and tiered permissions to ensure safe and controlled terminal interactions.
      40
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      A comprehensive MCP server for driving tmux sessions, windows, panes, sending keystrokes, and reading pane output locally or over SSH, enabling real-time collaborative pairing with AI.
      71
      6
      MIT