Iterm MCP

What ferrislucas/iterm-mcp MCP server does

The ferrislucas/iterm-mcp MCP server connects an MCP client to the active iTerm session. It gives an agent access to the terminal you are using rather than creating a separate terminal abstraction. An agent can issue a command, inspect the resulting screen output, ask questions about what is visible, and continue an interactive workflow.

The server is intended for macOS environments running iTerm2. It requires Node.js version 18 or later. The README describes the project as having minimal dependencies and being runnable through npx, which makes it suitable for a local MCP client configuration.

How it works

The ferrislucas/iterm-mcp MCP server communicates with the MCP client over standard input and output. Its terminal operations target the active iTerm terminal session.

Three tools provide the interface:

• write_to_terminal writes text to the active terminal, commonly to run a command. The tool reports how many output lines the command produced.
• read_terminal_output retrieves a requested number of lines from the active terminal.
• send_control_character sends a control character to the active terminal. This supports interactions such as interrupting or suspending a process with control characters like Ctrl-C or Ctrl-Z.

Reading only the lines needed by the agent can reduce unnecessary context when a command produces a large amount of output. Interactive programs and REPLs can also be started and operated through the terminal.

Setup and configuration

Start iTerm2 before using the server. Confirm that Node.js 18 or newer is installed, then add the server to the MCP client's configuration. The documented Claude Desktop configuration uses npx with the -y flag and the iterm-mcp package:

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

The README identifies the Claude Desktop configuration locations as ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%/Claude/claude_desktop_config.json on Windows. The server itself is described in the context of iTerm2, so iTerm2 availability remains a prerequisite.

For local development, the repository documents yarn install, yarn run build, and yarn run watch. It also documents an Inspector-based debugging workflow using the project's package scripts.

Tools and capabilities

The ferrislucas/iterm-mcp MCP server fits tasks that require direct terminal interaction rather than read-only command execution. An agent can run shell commands, read selected output from long-running work, operate a REPL, and send control characters when a process needs to be interrupted or suspended.

Because the tools write directly to the active terminal, the user can watch the agent's actions in the same iTerm session. This also makes the selected terminal state relevant: commands and reads apply to the active iTerm terminal exposed by the environment.

Limitations and notes

There are no built-in command safety restrictions. The server does not evaluate whether a command is safe before sending it to iTerm. Users are responsible for monitoring activity and stopping the agent when necessary. The README recommends beginning with smaller, focused tasks until the agent's behavior is familiar, particularly for multi-step operations.

The ferrislucas/iterm-mcp MCP server requires iTerm2 to be running and does not document an API key, OAuth flow, or hosted endpoint. The supplied material explicitly documents Claude Desktop setup; compatibility with other clients is not specified beyond describing the project as usable with other MCP clients.