mcp-registry/iterm-mcp

    ==================
      
       /// MCP ///
      /// ITE ///
        
    ==================
        
    [server:online]
    [protocol:ready]

iterm-mcp

by ferrislucas

Model Context Protocol (MCP) server that lets an AI model read from and write to the active iTerm2 terminal tab, enabling natural-language REPL/CLI interactions.

402
43
Open Source
GitHubDocumentationNPM

01

write_to_terminal

Writes to the active iTerm terminal, often used to run a command, and returns the number of lines of output produced by the command.

02

read_terminal_output

Reads the requested number of lines from the active iTerm terminal.

03

send_control_character

Sends a control character to the active iTerm terminal.

Installation

1. Prerequisites
• macOS with iTerm2 installed (>= v3.5)
• Node.js >=18 and npm (or yarn/pnpm)
• Allow "Applications in Terminal" scripting permission for iTerm2 (macOS Security & Privacy → Privacy → Automation)
2. Install the package globally
npm install -g iterm-mcp # or: yarn global add iterm-mcp
(Local install works too: `npm i iterm-mcp --save-dev` and call via npx.)
3. Start the MCP server
iterm-mcp start --port 3333 # default port 3333
4. Optional configuration
Create `~/.config/iterm-mcp/config.json` (or supply `--config <file>`) with:
{ "port": 3333, "allowUnsafe": false, "shell":"zsh" // or bash, fish, etc. }
5. Test
curl -X POST http://localhost:3333/v1/tools/execCurrentSession -d '{"command":"echo hello"}'
The text should appear in your active iTerm tab.
6. Autostart (optional)
Add to `~/.zprofile`:
(pgrep -f iterm-mcp || (iterm-mcp start --daemon &))

Documentation

License: MIT License
Updated 7/30/2025

Table of Contents