ITerm MCP Server

What is ITerm MCP Server about?

ITerm MCP Server provides a Model Context Protocol (MCP) interface that allows AI assistants to interact with iTerm2 terminals on macOS. It manages terminal sessions, runs commands, captures output, and reports the state of active terminals.

How to use ITerm MCP Server?

1. Install Node.js (>=14.x) on macOS.
2. Run the server using the provided MCP configuration, e.g., via Cursor:

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

3. Invoke supported tools (open_terminal, execute_command, read_output, close_terminal, list_terminals) from an AI assistant or any MCP client.

Key Features of ITerm MCP Server

• Create new iTerm2 terminal sessions.
• Execute arbitrary commands in a designated terminal.
• Read real‑time output from terminals.
• List all active terminals with their identifiers.
• Close terminals cleanly.
• Input validation using Zod schemas and robust error handling.

Use Cases of ITerm MCP Server

• AI‑driven DevOps: Automate routine shell tasks from an AI assistant.
• Live Coding Assistance: Let an AI guide a developer by executing code snippets in a terminal and showing results.
• Educational Tools: Provide step‑by‑step command line tutorials where the AI runs commands and displays output.
• Testing Automation: Trigger test suites or scripts inside iTerm2 sessions via conversational prompts.

FAQ from the ITerm MCP Server

• What platforms are supported? macOS only, because iTerm2 runs exclusively on macOS.
• Do I need any additional configuration? No; the server works with the default MCP configuration.
• How are commands secured? All inputs are validated with Zod schemas, and each command runs in its own isolated terminal session.
• Can I run this without Cursor? Yes; any MCP‑compatible client can invoke the server using the same npx iterm_mcp_server command.
• What license is the project under? ISC.

ITerm MCP Server

A Model Context Protocol (MCP) server implementation for iTerm2 terminal integration. This server allows AI assistants to interact with iTerm2 terminals through the Model Context Protocol.

Features

• Create and manage iTerm2 terminal sessions
• Execute commands in terminals
• Read terminal output
• List active terminals
• Close terminals

Requirements

• Node.js >= 14.x
• iTerm2
• macOS (since iTerm2 is macOS-only)

Configuration

Standard Configuration

The server uses the standard MCP configuration options. No additional configuration is required.

Cursor Configuration

To use this server with Cursor, add the following configuration to your ~/.cursor/mcp.json file:

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

Tools

• open_terminal: Open a new terminal instance
• execute_command: Execute a command in a specific terminal
• read_output: Read the output from a specific terminal
• close_terminal: Close a specific terminal
• list_terminals: List all active terminals and their information

Security Considerations

• The server validates all input using Zod schemas
• Commands are executed in isolated terminal sessions
• Proper error handling and input sanitization is implemented

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC

Author

Rishab Koul