How ferrislucas/iterm-mcp works
Project type and purpose
• iterm-mcp is a command-line–invoked MCP (Model Context Protocol) server written in TypeScript/Node.js.
• Its purpose is to expose an existing iTerm session to an external “model” by implementing three core tools over stdio:
• write_to_terminal
• read_terminal_output
• send_control_character
File structure
• Top-level:
• package.json, tsconfig.json, jest.config.cjs, LICENSE.md, README.md
• .github directory contains images and CI/GitHub configs
• src/ directory: the main TypeScript source files:
• index.ts (bootstraps the MCP stdio server, loads command handlers)
• CommandExecutor.ts (runs shell commands in the TTY)
• ProcessTracker.ts (tracks processes spawned by CommandExecutor)
• SendControlCharacter.ts (issues control keys to the terminal)
• TtyOutputReader.ts (reads output from the terminal)
• test/ directory:
• unit/ (unit tests for each module)
• e2e/ (end-to-end tests simulating real iTerm interactions)
README for additional insights
• Confirms that it’s purely a backend tool with no frontend UI.
• Describes its three “tools” as distinct logical services.
• Notes that it communicates solely over stdio following MCP conventions.
Main components and interactions
a. External MCP client (e.g., Claude Desktop)
b. Node.js + TypeScript runtime hosting the MCP server (index.ts)
c. Command Dispatcher (inside index.ts)
d. Module handlers:
– CommandExecutor (spawns shell commands in iTerm’s TTY)
– TtyOutputReader (captures output lines)
– SendControlCharacter (sends ctrl-c, ctrl-z, etc.)
– ProcessTracker (manages child processes’ lifecycle)
e. External dependency: iTerm2 application / the user’s terminal session
Flow of data:
1. MCP client → stdio JSON request → Node MCP server
2. Server routes the request to the appropriate handler module
3. Handler interacts with the iTerm TTY (via direct PTY or AppleScript)
4. TTY returns output or acknowledgement
5. Handler formats response → stdio JSON response → MCP client
Architectural patterns and design principles
• Single‐process, event-driven I/O model (Node.js)
• Command Handler pattern: each tool = one module
• Separation of concerns: dispatching, process management, I/O, control characters
• Minimal external dependencies: ease of distribution via npx