@thestarware/iterm-console-mcp

A Model Context Protocol (MCP) server for reading and filtering iTerm2 terminal logs and console output. Ideal for development workflows where you need to monitor and process live terminal output in real time.

Features

Live Terminal Output Reading: Reads output directly from iTerm2 terminal sessions, enabling real-time monitoring and processing.

Smart Filtering: Automatically filters out common noise patterns (e.g. custom patterns you define).

Flexible Integration: Designed to work seamlessly with Claude Desktop and other MCP clients.

Customizable Filtering: Supports user-defined filters to skip or include specific lines or patterns.

Tools

• read_terminal_output - Reads and filters lines from iTerm terminal output, with support for custom filtering and search.

Requirements

• Node version 18 or greater
• iTerm2 installed on macOS
• iTerm2 terminal must be active and running
• Appropriate permissions for AppleScript or automation (for reading iTerm output)

Installation

To use with Claude Desktop, add the server config:

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

{
  "mcpServers": {
    "iterm-console-mcp": {
      "command": "npx",
      "args": ["-y", "@thestarware/iterm-console-mcp"]
    }
  }
}

Usage

The server reads output from active iTerm terminal sessions. You can customize which output to retrieve and how it is filtered using the following parameters with the read_terminal_output tool:

• linesOfOutput (optional, number):
  The number of lines to return from the end of the terminal output. If not specified, all matching lines are returned.

• terminalName (optional, string):
  The name of the iTerm terminal session to read from. If not provided, the output from the last active terminal session is used.

• skipLines (optional, string array):
  An array of substrings. Any line containing one of these substrings will be excluded from the results.

• searchStrings (optional, string array):
  An array of strings. Only lines containing at least one of these strings will be included in the results.

Example

To read the last 100 lines from a terminal session named "dev-server", skipping lines containing "webpack" or "health check", and only including lines that mention "ERROR" or "WARN":

{
  "linesOfOutput": 100,
  "terminalName": "dev-server",
  "skipLines": ["webpack", "health check"],
  "searchStrings": ["ERROR", "WARN"]
}

Filtering

You can control which lines are included or excluded from the output using the skipLines and searchStrings parameters:

• skipLines:
  Excludes any line containing any of the specified substrings.

• searchStrings:
  Only includes lines containing at least one of the specified strings.

Both parameters can be used together for precise filtering. If neither is provided, all lines from the selected terminal session are returned (or limited by linesOfOutput).

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run dev

Or alternatively:

npm run watch

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.