iTerm Terminal Control MCP Server

Command LineTypeScript

Execute and interact with commands in your active iTerm terminal session

Available Tools

write_to_terminal

Writes to the active iTerm terminal, often used to run a command. Returns the number of lines of output produced by the command.

read_terminal_output

Reads the requested number of lines from the active iTerm terminal.

send_control_character

Sends a control character to the active iTerm terminal.

iTerm Terminal Control provides AI models with the ability to interact directly with your iTerm terminal sessions. It enables models to execute commands, read terminal output, and send control characters, making it ideal for CLI assistance and REPL interactions. This tool is designed with efficiency in mind, allowing models to inspect only the specific terminal output they need rather than the entire session history. The integration feels natural as you share your terminal with the model, which can help with troubleshooting, executing multi-step tasks, or interacting with command-line tools and programming language REPLs.

Overview

iTerm Terminal Control allows AI models to interact with your active iTerm terminal sessions. This enables the model to help you with command-line tasks, troubleshoot issues, and interact with REPLs (Read-Eval-Print Loops) for various programming languages.

Requirements

Before installing iTerm Terminal Control, ensure you have:

iTerm2 installed and running
Node.js version 18 or greater

Installation

For Claude Desktop

Create or edit the Claude Desktop configuration file:
- On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- On Windows: %APPDATA%/Claude/claude_desktop_config.json
Add the following configuration:

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

Using Smithery (Alternative Method)

You can also install iTerm Terminal Control automatically using Smithery:

npx -y @smithery/cli install iterm-mcp --client claude

Usage

Once installed, you can ask the AI model to:

Execute commands in your terminal
Read the output of commands
Send control characters (like Ctrl+C to interrupt processes)
Interact with REPLs for programming languages

Example Prompts

"Help me debug this Node.js error in my terminal"
"Show me how to use the git rebase command"
"Start a Python REPL and help me test some code"
"Execute a series of commands to set up a new project"

Safety Considerations

When using iTerm Terminal Control, keep these safety points in mind:

The tool has no built-in restrictions on command execution
You are responsible for monitoring the commands being executed
For complex multi-step tasks, be prepared to interrupt the model if needed
Start with smaller, focused tasks until you're comfortable with how the model interacts with your terminal

Troubleshooting

If you encounter issues:

Ensure iTerm2 is running and has an active session
Verify your Node.js version is 18 or greater
Check that the configuration in your Claude Desktop config file is correct
Restart Claude Desktop after making configuration changes