Iterm MCP

8 forks

141 stars

Free

What is iterm-mcp

iterm-mcp is a Model Context Protocol (MCP) server developed by ferrislucas. It serves as a bridge between your iTerm2 session and AI models, allowing seamless interaction and control over terminal sessions. By leveraging the protocol, iterm-mcp provides AI systems with the capability to interact with terminal outputs and execute commands in a controlled environment. This integration allows users to ask questions about terminal outputs or delegate tasks to AI models, making it a powerful tool for automating and enhancing terminal workflows.

How to Use iterm-mcp

To use iterm-mcp, ensure you have iTerm2 running on your system and Node.js version 18 or greater installed. The server can be easily operated through npx, enabling straightforward integration with clients like Claude Desktop. Here’s a basic setup guide:

Install via Command Line: Use npx to install and run iterm-mcp, providing a simple way to get started without dealing with complex dependencies.
Integrate with Claude Desktop: Modify your Claude Desktop configuration file to include iterm-mcp, enabling the server to manage and interact with your iTerm2 session seamlessly. Configuration can be done through a JSON file where you specify the server's command and arguments.
Automate with Smithery: For an even more streamlined installation, utilize Smithery to automatically set up iterm-mcp for use with Claude Desktop.

Once set up, iterm-mcp allows you to execute commands, read outputs, and send control characters directly through your iTerm session, facilitating a dynamic and interactive workflow.

Key Features of iterm-mcp

Efficient Token Use: The server intelligently manages terminal output, allowing models to focus on the most recent and relevant data. This is particularly useful for long-running commands where only the latest outputs are of interest.
Natural Integration: Share your iTerm session with AI models to ask questions about displayed outputs or delegate tasks. Watch as the model performs tasks step-by-step, providing a natural and interactive experience.
Full Terminal Control: iterm-mcp supports full terminal control, including the ability to start and interact with REPL environments and send control characters like ctrl-c and ctrl-z.
Minimal Dependencies: Designed with simplicity in mind, iterm-mcp runs with minimal dependencies, making it easy to deploy and integrate into existing systems.
Safety Considerations: While iterm-mcp provides powerful control over terminal sessions, it includes no built-in safety restrictions. Users are responsible for monitoring AI activity to ensure safe usage, starting with smaller tasks as they familiarize themselves with the tool.

With these features, iterm-mcp enhances your terminal interactions by providing a robust interface for AI-driven tasks, making your workflow more efficient and intelligent.

A Model Context Protocol server that provides access to your iTerm session. Main Image

Features

Efficient Token Use: iterm-mcp gives the model the ability to inspect only the output that the model is interested in. The model typically only wants to see the last few lines of output even for long running commands. Natural Integration: You share iTerm with the model. You can ask questions about what's on the screen, or delegate a task to the model and watch as it performs each step. Full Terminal Control and REPL support: The model can start and interact with REPL's as well as send control characters like ctrl-c, ctrl-z, etc. Easy on the Dependencies: iterm-mcp is built with minimal dependencies and is runnable via npx. It's designed to be easy to add to Claude Desktop and other MCP clients. It should just work.

Safety Considerations

The user is responsible for using the tool safely.
No built-in restrictions: iterm-mcp makes no attempt to evaluate the safety of commands that are executed.
Models can behave in unexpected ways. The user is expected to monitor activity and abort when appropriate.
For multi-step tasks, you may need to interrupt the model if it goes off track. Start with smaller, focused tasks until you're familiar with how the model behaves.

Tools

write_to_terminal - Writes to the active iTerm terminal, often used to run a command. Returns the number of lines of output produced by the command.
read_terminal_output - Reads the requested number of lines from the active iTerm terminal.
send_control_character - Sends a control character to the active iTerm terminal.

Requirements

iTerm2 must be running
Node version 18 or greater

Installation

To use with Claude Desktop, add the server config: On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

 "mcpServers": {
 "iterm-mcp": {
 "command": "npx",
 "args": [
 "-y",
 "iterm-mcp"

Installing via

To install iTerm for Claude Desktop automatically via :

npx -y @/cli install iterm-mcp --client claude

Development

Install dependencies:

yarn install

Build the server:

yarn run build

For development with auto-rebuild:

yarn run watch

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

yarn run inspector
yarn debug <command>

The Inspector will provide a URL to access debugging tools in your browser.

How to Use

To use the iterm-mcp, follow these steps:

Visit https://github.com/ferrislucas/iterm-mcp
Follow the setup instructions to create an account (if required)
Connect the MCP server to your Claude Desktop application
Start using iterm-mcp capabilities within your Claude conversations

Additional Information

Created

January 9, 2025

Company

ferrislucas

Related MCP Servers

Start building your own MCP Server

Interested in creating your own MCP Server? Check out the official documentation and resources.

Learn More