# ferrislucas/iterm-mcp [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/ferrislucas/iterm-mcp  
**GitHub Stars:** 567  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ferrislucas-iterm-mcp

## Description
A Model Context Protocol server that provides access to iTerm. You can run commands and ask questions about what you see in the iTerm terminal.

## Tools
Capabilities this server exposes over MCP:

- **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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "iterm-mcp": {
    "command": "npx",
    "args": ["-y","@smithery/cli"]
  }
}
```

## Documentation

## 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:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/ferrislucas-iterm-mcp/readme_