Iterm2 Agent

🚀 iterm2-agent

iTerm2のPython APIを介してiTerm2ターミナルセッションを制御するためのMCPサーバーです。

Model Context Protocolを通じて、画面の読み取り、コマンドの実行、キーストロークの送信、出力の監視、ペインの管理などを行うことができます。

🚀 クイックスタート

前提条件

• iTerm2がインストールされたmacOS
• iTerm2のPython APIを有効にする: Preferences → General → Magic → Enable 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             # 実行するシェルコマンド
timeout: int = 30        # 最大待機時間（秒）
session_id: str = ""

コマンドはセキュリティガードによって分類されます。

• SAFE — 読み取り専用コマンド (ls, pwd, git status, ...)
• CAUTION — 変更を加えるコマンド (mkdir, npm install, git push, ...)
• DANGEROUS — 破壊的なコマンド (rm, sudo, kill, ...) — 警告が表示されます

send_text

セッションにテキストを送信し、自動的にEnterキーを押さないでください。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 = ""     # close/focusでは必須、splitではオプション
direction: str = "horizontal"  # horizontal | vertical (splitのみ)

📚 ドキュメント

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セッションを開始して、以下のコマンドを試してみてください。

• "What's on my terminal right now?"
• "Run git status in iTerm2"
• "Split the terminal and run tests in the new pane"
• "Start the dev server and tell me when it's ready"
• "Send Ctrl+C to stop the running process"

アーキテクチャ

┌─────────────────────────────────────┐
│         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