Iterm2 Agent

🚀 iterm2-agent

iterm2-agent 是一個 MCP 服務器，可通過 iTerm2 Python API 控制 iTerm2 終端會話。藉助 Model Context Protocol，你可以讀取屏幕內容、運行命令、發送按鍵、監控輸出以及管理面板。

🚀 快速開始

前提條件

• 安裝了 iTerm2 的 macOS 系統。
• 啟用 iTerm2 Python API：偏好設置 → 常規 → 魔法 → 啟用 Python API。
• Python 3.11 及以上版本。
• uv（可通過 brew install uv 安裝）。

安裝步驟

MCP 服務器

git clone git@github.com:xjthy001/iterm2-agent.git
cd iterm2-agent
uv venv
uv pip install -e .

然後在 ~/.claude.json 中註冊它（詳見下面的 與 Claude Code 配合使用）。

技能（可選）

可通過 skills.sh 安裝代理技能：

npx skills add xjthy001/iterm2-agent

或者手動安裝：

mkdir -p ~/.claude/skills/iterm2-agent
cp skills/iterm2-agent/SKILL.md ~/.claude/skills/iterm2-agent/SKILL.md

該技能為你的 AI 代理提供了有效使用 6 種工具的參考指南。當你提及 iTerm2 或終端控制時，它會自動激活。

✨ 主要特性

工具列表

read_screen

讀取會話的可見屏幕內容。

lines: int = -1          # 要讀取的行數 (-1 表示所有可見行)
session_id: str = ""     # 目標會話（空表示活動會話）

run_command

執行命令並捕獲輸出。在返回結果之前，會等待輸出穩定（空閒 2 秒）。

command: str             # 要執行的 shell 命令
timeout: int = 30        # 最大等待秒數
session_id: str = ""

命令由安全防護機制進行分類：

• 安全（SAFE） — 只讀命令（如 ls、pwd、git status 等）。
• 謹慎（CAUTION） — 修改命令（如 mkdir、npm install、git push 等）。
• 危險（DANGEROUS） — 破壞性命令（如 rm、sudo、kill 等），會產生警告。

send_text

向會話發送文本，不自動按下回車鍵。設置 press_enter=true 可提交。

text: str                # 要發送的文本
press_enter: bool = false
session_id: str = ""

send_control

發送控制字符。

character: str           # 可選值: C, Z, D, L, ESCAPE, A, E, U, K, W, R
session_id: str = ""

watch_output

阻塞直到屏幕上出現正則表達式模式，或達到超時時間。

pattern: str             # 要匹配的正則表達式模式
timeout: int = 60        # 最大等待秒數
session_id: str = ""

manage_session

管理 iTerm2 會話。

action: str              # list | create | split | close | focus
session_id: str = ""     # 關閉/聚焦操作必需，分割操作可選
direction: str = "horizontal"  # horizontal | vertical (僅分割操作有效)

💻 使用示例

與 Claude Code 配合使用

1. 註冊 MCP 服務器

在 ~/.claude.json 的 mcpServers 對象中添加 iterm2-agent 條目：

{
  "mcpServers": {
    "iterm2-agent": {
      "type": "stdio",
      "command": "/path/to/iterm2-agent/.venv/bin/python",
      "args": ["-m", "iterm2_agent"]
    }
  }
}

將 /path/to/iterm2-agent 替換為你實際的克隆路徑。該命令必須指向項目虛擬環境中的 Python 二進制文件，以便依賴項可用。

如果 ~/.claude.json 中已經有 mcpServers 對象，只需在現有服務器旁邊添加 "iterm2-agent": { ... } 條目，不要覆蓋整個文件。

編輯後重啟 Claude Code。服務器在啟動時會連接到 iTerm2，請確保 iTerm2 正在運行且 Python API 已啟用。

2. 安裝技能（可選）

npx skills add xjthy001/iterm2-agent

或者從倉庫手動複製：

mkdir -p ~/.claude/skills/iterm2-agent
cp skills/iterm2-agent/SKILL.md ~/.claude/skills/iterm2-agent/SKILL.md

安裝後，可使用 /iterm2-agent 調用它，或者當你提及終端/iTerm2 時，它會自動激活。

3. 驗證

啟動一個新的 Claude Code 會話並嘗試以下操作：

• "我當前終端上有什麼內容？"
• "在 iTerm2 中運行 git status"
• "分割終端並在新面板中運行測試"
• "啟動開發服務器並在準備好時通知我"
• "發送 Ctrl+C 停止正在運行的進程"

🔧 技術細節

架構

┌─────────────────────────────────────┐
│         MCP Client                  │
│   (Claude Code / Claude Desktop)    │
└──────────────┬──────────────────────┘
               │ stdio (JSON-RPC)
┌──────────────▼──────────────────────┐
│       iterm2-agent (MCP Server)     │
│                                     │
│  server.py        FastMCP + lifespan│
│  connection.py    Session resolver  │
│  security.py      Command classifier│
│  tools/                             │
│    read_screen.py                   │
│    run_command.py                   │
│    send_text.py                     │
│    send_control.py                  │
│    watch_output.py                  │
│    manage_session.py                │
└──────────────┬──────────────────────┘
               │ WebSocket
┌──────────────▼──────────────────────┐
│         iTerm2 Python API           │
│     (iterm2.Connection)             │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│           iTerm2.app                │
└─────────────────────────────────────┘

項目結構

iterm2-agent/
├── pyproject.toml
├── config/
│   └── default.toml
├── src/iterm2_agent/
│   ├── __init__.py
│   ├── __main__.py           # 入口點: python -m iterm2_agent
│   ├── server.py             # 帶有 iTerm2 生命週期的 FastMCP 服務器
│   ├── connection.py         # iTerm2Context、會話解析、屏幕讀取
│   ├── security.py           # 命令分類 (SAFE/CAUTION/DANGEROUS)
│   └── tools/
│       ├── __init__.py       # 工具註冊
│       ├── read_screen.py
│       ├── run_command.py
│       ├── send_text.py
│       ├── send_control.py
│       ├── watch_output.py
│       └── manage_session.py
├── tests/
│   ├── test_security.py      # 安全防護單元測試
│   ├── test_read_screen.py   # 會話解析單元測試
│   ├── test_run_command.py   # 安全集成測試
│   └── test_send_control.py  # 控制字符映射測試
├── test_integration.py       # 即時集成測試 (需要 iTerm2)
└── skills/iterm2-agent/
    └── SKILL.md              # 代理技能定義 (與 skills.sh 兼容)

測試

單元測試（無需 iTerm2）

uv pip install pytest pytest-asyncio
uv run pytest

即時集成測試（需要運行 iTerm2）

uv run python test_integration.py

📄 許可證

本項目採用 MIT 許可證。