iterm-mcp

Name: iterm-mcp
Author: ferrislucas

@ferrislucas

About iterm-mcp

A Model Context Protocol server that executes commands in the current iTerm session - useful for REPL and CLI assistance

#ai #mcp #repl #claude #claude-ai #mcp-server

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

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

Tools

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

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

Sends a control character to the active iTerm terminal.

Overview

What is iterm-mcp?

iterm-mcp is a Model Context Protocol server that provides access to your iTerm session. It allows large language models to inspect terminal output, write commands, and send control characters directly to iTerm2.

How to use iterm-mcp?

Install iterm-mcp via npx (npx -y iterm-mcp) and add the server configuration to your MCP client, such as the Claude Desktop config file (claude_desktop_config.json). For a one‑click install, you can also use Smithery (npx -y @smithery/cli install iterm-mcp --client claude). iTerm2 must be running and Node version 18 or higher is required.

Key features of iterm-mcp

Efficient token use: model inspects only the output it needs.
Natural integration: share iTerm with the model and watch it work.
Full terminal control and REPL support with control characters.
Minimal dependencies, runnable via npx.
Easy setup with Claude Desktop and other MCP clients.

Use cases of iterm-mcp

Inspect the last few lines of output from long‑running commands.
Delegate multi‑step terminal tasks and observe each step.
Start and interact with REPLs (e.g., Python, Node).
Send control characters like ctrl‑c or ctrl‑z to manage processes.

FAQ from iterm-mcp

What are the safety considerations?

The user is responsible for using the tool safely. iterm‑mcp makes no attempt to evaluate the safety of commands, and models can behave unexpectedly. Users should monitor activity and abort when appropriate.

What are the system requirements?

iTerm2 must be running. Node version 18 or greater is required.

How do I install iterm-mcp for Claude Desktop?

Add the following entry to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json): {"mcpServers":{"iterm-mcp":{"command":"npx","args":["-y","iterm-mcp"]}}}.

What tools does iterm-mcp provide?

Three tools: write_to_terminal (writes to the active terminal and returns line count), read_terminal_output (reads a requested number of lines), and send_control_character (sends control characters like ctrl‑c).