iterm2-py-mcp 0.1.0

MCP server for iTerm2 — read terminal output (and optionally drive sessions) from Claude Desktop

iterm2-py-mcp-server

MCP server for iTerm2 on macOS, written in pure Python. Lets Claude (Desktop, primarily) read what's on your terminal screens and scrollback, search inside long log dumps, and — optionally, behind a feature flag — drive iTerm2 sessions by sending text or control keys.

Status: v0.1.0, stages 0–4 complete; 8 readonly tools always available, 4 write tools behind ITERM_MCP_ALLOW_WRITE=1. See docs/PLAN.md for full status and docs/TOOLS.md for the tool reference.

Why

When you're SSH'd into a remote box and tail something long — logs, a process tree, a journalctl dump — pasting it into Claude is tedious and lossy. This MCP server gives Claude a direct, read-only window into the terminal you're already looking at, so you can just ask questions about it.

Quick start

# Install from source into the current Python environment
pip install -e .

# Or run without installing (once published)
uvx iterm2-py-mcp

Then add to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "iterm2": {
      "command": "iterm2-py-mcp"
    }
  }
}

Full setup walk-through (enabling the iTerm2 Python API, granting access, verifying with iterm_status) lives in docs/INSTALL.md.

Documentation

Doc	What's in it
docs/README.md	Documentation index
docs/PLAN.md	Roadmap, stages, what's done / TODO
docs/INSTALL.md	Install, build, configure Claude Desktop
docs/ARCHITECTURE.md	How it's wired internally
docs/TOOLS.md	Reference for every MCP tool
docs/TROUBLESHOOTING.md	Common errors and fixes
docs/IDEAS.md	Backlog of possible future features

License

GNU Lesser General Public License v3.0 (LGPLv3).