iterm-mcp MCP Server

What does “iterm-mcp” MCP Server do?

The iterm-mcp MCP Server is a Model Context Protocol server designed to provide AI assistants with direct access to your iTerm session. This powerful tool enables large language models (LLMs) to execute commands, interact with REPLs, and manage terminal workflows within the currently active iTerm terminal. By bridging AI clients to the terminal environment, iterm-mcp enhances development workflows through natural, shared access—facilitating tasks such as running shell commands, inspecting terminal output, and sending control characters (e.g., interrupt signals). Its efficient token usage ensures only relevant output is surfaced, and its minimal dependencies make it easy to integrate with platforms like Claude Desktop and other MCP-enabled clients, streamlining CLI and REPL assistance for developers.

List of Prompts

No prompt templates are explicitly mentioned in the repository.

List of Resources

No explicit resources are documented in the repository.

List of Tools

• write_to_terminal
  Writes input to the active iTerm terminal session. Commonly used to run shell commands and returns the number of output lines produced.

• read_terminal_output
  Reads a specified number of lines from the active iTerm terminal output, allowing models to retrieve recent terminal activity.

• send_control_character
  Sends control characters (like Ctrl+C or Ctrl+Z) to the active iTerm terminal, supporting process interruption or suspension.

Use Cases of this MCP Server

• REPL Automation and Assistance
  Enables LLMs to interact with live REPL sessions, executing commands, inspecting results, and managing multi-step workflows interactively.

• CLI Workflow Automation
  Allows AI agents to execute and monitor shell commands, automate routine development tasks, and handle output parsing or error handling.

• Terminal Output Inspection
  Models can inspect the current or past terminal output, answer questions about what’s on the screen, and assist with debugging or log analysis.

• Process Management
  Through control characters, developers can delegate process interruption, suspension, or continuation tasks to AI assistants for improved workflow safety.

• Code Execution and Testing
  Facilitates running code snippets or scripts directly within the terminal, with the AI model capturing outputs and iterating based on results.

How to set it up

Windsurf

1. Ensure Node.js (v18 or later) and iTerm2 are installed and running on your Mac.
2. Locate your Windsurf configuration file (consult Windsurf documentation for the path).
3. Add the iterm-mcp MCP server configuration under the mcpServers section:

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

4. Save the configuration file and restart Windsurf.
5. Verify the setup by attempting to connect to iterm-mcp from the Windsurf interface.

Securing API keys:
If the server requires environment variables or secrets, add them as follows:

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

Claude

1. Ensure Node.js (v18 or later) and iTerm2 are installed and running on your Mac.
2. Open the Claude Desktop configuration file:
   ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
   %APPDATA%/Claude/claude_desktop_config.json (Windows)
3. Add the iterm-mcp server to your mcpServers section:

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

4. Save the file and restart Claude Desktop.
5. Confirm the server is available in the Claude interface.

Securing API keys:
Add secrets under the env object as needed.

Cursor

1. Install Node.js (v18+) and ensure iTerm2 is running.
2. Open your Cursor configuration file (location as per Cursor documentation).
3. Insert the following configuration:

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

4. Save and restart Cursor.
5. Test the connection from within Cursor.

Securing API keys:
Add secrets via the env attribute.

Cline

1. Make sure Node.js (v18+) and iTerm2 are installed and running.
2. Find your Cline configuration file.
3. Add the following configuration:

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

4. Save and restart Cline.
5. Verify setup by connecting to the iTerm MCP server.

Securing API keys:
Configure secrets as environment variables in the config, e.g.:

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

How to use this MCP inside flows

Using MCP in FlowHunt

To integrate MCP servers into your FlowHunt workflow, start by adding the MCP component to your flow and connecting it to your AI agent:

Click on the MCP component to open the configuration panel. In the system MCP configuration section, insert your MCP server details using this JSON format:

{
  "iterm-mcp": {
    "transport": "streamable_http",
    "url": "https://yourmcpserver.example/pathtothemcp/url"
  }
}

Once configured, the AI agent is now able to use this MCP as a tool with access to all its functions and capabilities. Remember to change “MCP-name” to whatever the actual name of your MCP server is (e.g., “github-mcp”, “weather-api”, etc.) and replace the URL with your own MCP server URL.

Overview

Based on the available information, iterm-mcp offers robust terminal integration and tool exposure, with clear setup instructions and security guidance, but lacks documented prompt templates, explicit resources, and advanced MCP features like roots and sampling. This makes it suitable for terminal-centric workflows, but less feature-rich for broader MCP contexts.

MCP Score