This project provides a Model Context Protocol (MCP) server for iTerm, enabling AI models to interact directly with the user's terminal session. It's designed for developers and power users seeking to integrate AI assistance into their command-line workflows, offering REPL support and full terminal control for tasks like code execution and debugging.

How It Works

iterm-mcp acts as a bridge between an AI model and the iTerm terminal. It leverages the Model Context Protocol to allow models to send commands, read terminal output, and send control characters (e.g., Ctrl+C). This approach enables efficient token usage by allowing models to inspect only relevant output, typically the last few lines of a command's execution.

Quick Start & Requirements

• Install/Run: npx -y iterm-mcp (for Claude Desktop integration) or npx -y @smithery/cli install iterm-mcp --client claude for automatic installation.
• Prerequisites: iTerm2 must be running; Node.js version 18 or greater.
• Setup: Configuration involves adding a JSON entry to claude_desktop_config.json.
• Docs: Claude Desktop Configuration

Highlighted Details

• Enables AI models to execute commands, read terminal output, and send control characters within an iTerm session.
• Supports REPL interactions and efficient token usage by focusing on relevant output.
• Designed for minimal dependencies and easy integration with MCP clients like Claude Desktop.

Maintenance & Community

• Developed by ferrislucas.
• Development install via yarn install, build via yarn run build, watch/auto-rebuild via yarn run watch.
• Debugging support via yarn run inspector.

Licensing & Compatibility

• The README does not explicitly state a license.

Limitations & Caveats

The project has no built-in safety restrictions; users are responsible for monitoring AI activity and aborting potentially unsafe commands. Models may behave unexpectedly, requiring user intervention for multi-step tasks.