playbooks

home / mcp / iterm mcp server

ITerm MCP Server

A MCP server for iTerm2 terminals enabling creation, command execution, output reading, listing, and closing of terminals via MCP.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "rishabkoul-iterm-mcp-server": {
      "command": "npx",
      "args": [
        "iterm_mcp_server"
      ]
    }
  }
}

You can control iTerm2 terminals through an MCP server, enabling AI assistants to open terminals, run commands, read outputs, list active sessions, and close terminals. This makes terminal automation and orchestration straightforward from any MCP client.

How to use

Use an MCP client to connect to the ITerm MCP Server and perform these actions: create a new terminal session, run commands inside a terminal, read the real-time output, list all active terminals, and close terminals when you’re done. Each operation maps to one of the available tools and can be chained to build complex workflows.

How to install

Prerequisites you must meet before running the server.

  • Node.js 14.x or newer
  • iTerm2 installed on macOS
  • macOS as the host OS

Start by making the MCP server accessible to your MCP clients. The recommended approach for local usage is to run the server through npx, which executes the MCP server package without a global install.

Optionally, you can integrate with Cursor by adding the following configuration to your MCP client setup. This enables easy access to the ITerm MCP Server from Cursor.

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["iterm_mcp_server"]
    }
  }
}

Additional configuration and usage notes

Standard MCP configuration is sufficient for normal use. The provided Cursor integration demonstrates how to expose the ITerm MCP Server as a terminal handler via npx, enabling clients to connect and manage terminals.

Available tools

open_terminal

Open a new iTerm2 terminal session to run commands within a dedicated process.

execute_command

Execute a given shell command inside a specific terminal session and capture its output.

read_output

Read and stream the real-time output from a terminal session.

close_terminal

Close a specified terminal session when it is no longer needed.

list_terminals

List all active terminals and their current state, including identifiers and metadata.