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)

$3

- 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

``bash
npm install -g mcpretentious
`

$3

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

$3


Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
`json
{
"mcpServers": {
"mcpretentious": {
"command": "npx",
"args": ["mcpretentious"]
}
}
}
`

$3

`bash
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

`bash
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