MCPretentious
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCPretentious open a new terminal and run 'ls -la'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-typetoolAlt + Letters (a-z):
alt-athroughalt-zAlt + Shift + Letters:
alt-shift-athroughalt-shift-zfor uppercaseAlt + Numbers (0-9):
alt-0throughalt-9Alt + Navigation keys: arrow keys, home, end, pageup, pagedown
Alt + Function keys (F1-F12):
alt-f1throughalt-f12Alt + 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 mcpretentiousPrerequisites
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 mcpretentiousMain 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 sessionmcpretentious-type- Send text/keys/ASCII codesmcpretentious-screenshot- Get screen content (configurable layers)mcpretentious-mouse- Send mouse events (SGR protocol)mcpretentious-resize- Set terminal dimensionsmcpretentious-close- Close terminalmcpretentious-list- List active terminals
Testing
npx mcpretentious-test # Basic test
npx mcpretentious-test --verbose # Detailed outputSecurity
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 toolsmcpretentious-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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI assistants the ability to create, manage, and control terminal sessions through a safe, isolated tmux environment.1ISC
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- AlicenseAqualityDmaintenanceAn 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.402MIT
- AlicenseBqualityBmaintenanceA 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.716MIT