How to add iTerm MCP server to Codex

Adding iTerm MCP to Codex gives a session direct access to the terminal you already have open in iTerm2. That is useful when a task needs to inspect live shell output, continue working inside an existing REPL, or send input to the terminal you are already watching instead of launching a separate subprocess.

The upstream server is a local stdio MCP server launched with npx -y iterm-mcp. In Codex, codex mcp add stores that launcher in ~/.codex/config.toml, and codex mcp get --json or codex mcp list confirms that the saved entry points to the expected npx command before a session tries to use it. That saved configuration is shared between the Codex CLI and IDE extension.

Current upstream requirements are iTerm2 running on macOS and Node.js 18 or newer. The server can write to the active iTerm2 session, including REPL input and control characters, so treat it like local terminal automation and keep the first test prompt short and deliberate.

1. Add the standard iTerm MCP launcher to Codex.

   $ codex mcp add iterm-mcp-server -- npx -y iterm-mcp
   Added global MCP server 'iterm-mcp-server'.

   -y suppresses the initial npx install prompt, and the saved name iterm-mcp-server gives you a predictable label for later codex mcp get or codex mcp remove commands.

2. Retrieve the saved MCP entry in JSON to confirm that Codex stored the expected local stdio server.

   $ codex mcp get iterm-mcp-server --json
   {
     "name": "iterm-mcp-server",
     "enabled": true,
     "disabled_reason": null,
     "transport": {
       "type": "stdio",
       "command": "npx",
       "args": [
         "-y",
         "iterm-mcp"
       ],
       "env": null,
       "env_vars": [],
       "cwd": null
     },
     "enabled_tools": null,
     "disabled_tools": null,
     "startup_timeout_sec": null,
     "tool_timeout_sec": null
   }

   "type": "stdio" plus the saved command and args values confirms that Codex will launch a local iTerm MCP process. The same entry is written under [mcp_servers.iterm-mcp-server] in ~/.codex/config.toml.

3. List configured MCP servers and confirm that the new entry is enabled.

   $ codex mcp list
   Name              Command  Args          Env  Cwd  Status   Auth
   iterm-mcp-server  npx      -y iterm-mcp  -    -    enabled  Unsupported

   The decisive success state for the add flow is the iterm-mcp-server row with enabled under Status. The Unsupported value under Auth is expected for this local stdio server because it does not use a separate login flow.

4. Start or restart Codex and send a short prompt that targets the active iTerm2 session.

   Read the last 20 lines from the active iTerm terminal.

   A successful answer proves that Codex can launch the saved server and inspect the terminal you currently have focused in iTerm2.

   iTerm MCP can send input and control characters to the active terminal session. Keep a safe tab or pane focused for the first test, and interrupt the model immediately if it starts acting on the wrong shell.