iterminator-mcp

iTerminator MCP

A powerful Model Context Protocol (MCP) server that puppeteers iTerm2 terminals. iTerminator enables AI assistants to fully control iTerm2 terminals - executing commands, interacting with TUI applications, and handling complex terminal workflows through the Model Context Protocol.

Latest Changes (v1.1.0 - 2025-08-22)

Changed

• Version bump to 1.1.0
• See CHANGELOG.md for details

For full changelog, see CHANGELOG.md

Features

• Create and manage iTerm2 terminal sessions
• Universal input method for text, special keys, and ASCII codes
• Read terminal output including TUI applications
• List and track active terminals
• VS Code and Electron-based editor compatibility
• Proper command escaping for security

Requirements

• Node.js >= 14.x
• iTerm2 (latest version recommended)
• macOS (iTerm2 is macOS-only)

Installation

Via npm (recommended)

npm install -g iterminator-mcp

From source

git clone https://github.com/oetiker/iterminator-mcp.git
cd iterminator-mcp
npm install
npm link

Configuration

Claude Code Configuration

The easiest way to add this server to Claude Code:

claude mcp add iterminator-mcp npx iterminator-mcp

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "iterminator": {
      "command": "npx",
      "args": ["iterminator-mcp"]
    }
  }
}

Cursor Configuration

For Cursor IDE, add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "iterminator": {
      "command": "npx",
      "args": ["iterminator-mcp"]
    }
  }
}

Available Tools

iterminator-open

Opens a new iTerm2 terminal window.

Returns: Terminal ID for subsequent operations

Example Response:

{
  "terminalId": "iterm-12345-1"
}

iterminator-type

Send text and keystrokes to a terminal. This is the universal input method that replaces the old execute-command, send-keys, and clear-terminal tools.

Parameters:

• terminalId (string, required): ID of the terminal
• input (string | number | object | array): Input to send, can be:
  • String: Normal text to type (e.g., "ls -la")
  • Number: ASCII/extended ASCII code 0-255 (e.g., 32 for space, 169 for ©)
  • Object: Special key as {key: 'name'} (e.g., {key: "enter"})
  • Array: Mix of the above for complex sequences

Supported Special Keys:

• Navigation: tab, shift-tab, enter, return, escape, esc, backspace, delete
• Arrows: up, down, left, right
• Movement: home, end, pageup, pagedown
• Control: ctrl-a through ctrl-z
• Function: f1 through f12

Examples:

// Simple command execution
{
  "terminalId": "iterm-12345-1",
  "input": ["ls -la", {"key": "enter"}]
}

// Navigate in TUI
{
  "terminalId": "iterm-12345-1",
  "input": [{"key": "up"}, {"key": "up"}, {"key": "enter"}]
}

// Complex typing with special characters
{
  "terminalId": "iterm-12345-1",
  "input": ["Hello", 32, "world", {"key": "backspace"}, "!", 169]
}

// Clear terminal
{
  "terminalId": "iterm-12345-1",
  "input": {"key": "ctrl-l"}
}

iterminator-read

Reads output from a terminal session. Can read either the visible viewport or the entire scrollback buffer.

Parameters:

• terminalId (string, required): ID of the terminal
• lines (number, optional): Number of lines to read from the bottom
• visible_only (boolean, optional): If true, returns only what's visible on screen (viewport). If false or omitted, returns the entire scrollback buffer. Essential for TUI debugging.

Examples:

// Read entire scrollback (default)
{
  "terminalId": "iterm-12345-1"
}

// Read only visible screen (for TUI debugging)
{
  "terminalId": "iterm-12345-1",
  "visible_only": true
}

// Read last 10 lines from scrollback
{
  "terminalId": "iterm-12345-1",
  "lines": 10
}

iterminator-close

Closes the iTerm2 window associated with the terminal ID.

Parameters:

• terminalId (string, required): ID of the terminal

iterminator-list

Lists all currently open iTerm2 terminal sessions.

Returns: List of active terminal IDs and iTerm status

Usage Examples

Basic Terminal Interaction

// Open a new terminal
const terminal = await use_mcp_tool("iterminator", "iterminator-open");
// Returns: { terminalId: "iterm-12345-1" }

// Execute a command
await use_mcp_tool("iterminator", "iterminator-type", {
  terminalId: "iterm-12345-1",
  input: ["ls -la", {key: "enter"}]
});

// Read the output
const output = await use_mcp_tool("iterminator", "iterminator-read", {
  terminalId: "iterm-12345-1"
});

// Clear the terminal
await use_mcp_tool("iterminator", "iterminator-type", {
  terminalId: "iterm-12345-1",
  input: {key: "ctrl-l"}
});

// Close when done
await use_mcp_tool("iterminator", "iterminator-close", {
  terminalId: "iterm-12345-1"
});

TUI Application Testing

// Open terminal and run a TUI app
const terminal = await use_mcp_tool("iterminator", "iterminator-open");
await use_mcp_tool("iterminator", "iterminator-type", {
  terminalId: "iterm-12345-1",
  input: ["vim test.txt", {key: "enter"}]
});

// Navigate and edit
await use_mcp_tool("iterminator", "iterminator-type", {
  terminalId: "iterm-12345-1",
  input: [
    "i",                    // Enter insert mode
    "Hello, World!",        // Type text
    {key: "escape"},        // Exit insert mode
    ":wq",                  // Save and quit command
    {key: "enter"}          // Execute command
  ]
});

// Read the visible TUI state (not scrollback)
const tuiState = await use_mcp_tool("iterminator", "iterminator-read", {
  terminalId: "iterm-12345-1",
  visible_only: true        // Only get what's on screen for TUI debugging
});

Interactive Password Entry

// Run sudo command
await use_mcp_tool("iterminator", "iterminator-type", {
  terminalId: "iterm-12345-1",
  input: ["sudo apt update", {key: "enter"}]
});

// Type password (won't be visible)
await use_mcp_tool("iterminator", "iterminator-type", {
  terminalId: "iterm-12345-1",
  input: ["mypassword", {key: "enter"}]
});

Working with Special Characters

// Type text with special characters using ASCII codes
await use_mcp_tool("iterminator", "iterminator-type", {
  terminalId: "iterm-12345-1",
  input: [
    "Copyright ", 169,      // © symbol
    " 2024", 32,           // space
    "My Company", 8482     // ™ symbol
  ]
});

Troubleshooting

Common Issues

• iTerm2 not responding: Ensure iTerm2 is installed and accessible. The server uses AppleScript to control iTerm2.

• Permission denied errors: macOS may require permissions for terminal automation. Check System Preferences > Security & Privacy > Privacy > Automation.

• Commands not executing: Remember to add {key: "enter"} after commands to execute them.

• VS Code focus issues: The server properly handles VS Code and other Electron-based editors. Ensure you're using the latest version.

• Special characters: Use ASCII codes (0-255) for special characters that can't be typed normally.

Debug Mode

To run with debug output:

DEBUG=* npx iterminator-mcp

API Migration Guide

If you're upgrading from an older version, here's how to update your code:

Old API	New API
execute-command with command: "ls"	iterminator-type with input: ["ls", {key: "enter"}]
send-keys with keys: "tab"	iterminator-type with input: {key: "tab"}
send-keys with text: "hello"	iterminator-type with input: "hello"
clear-terminal	iterminator-type with input: {key: "ctrl-l"}

Security Considerations

• Input validation using Zod schemas
• Proper command escaping for AppleScript
• Isolated terminal sessions
• No direct shell execution without terminal context

Changelog

See CHANGELOG.md for a list of changes and upcoming features.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

• Fork the repository
• Clone your fork
• Install dependencies: npm install
• Make your changes
• Test locally: npm link then configure your MCP client
• Submit a pull request

Running Tests

npm test

License

ISC

Author

Tobi Oetiker

Acknowledgments

• Built for the Model Context Protocol
• Designed for Claude Desktop and other MCP-compatible clients