Iterm2 Agent

iterm2代理

MCP服务器，用于通过iTerm2 Python API控制iTerm2终端会话。

读取屏幕、运行命令、发送击键、监视输出和管理窗格——全部通过 模型上下文协议.

先决条件

• macOS与 iTerm2 安装
• iTerm2 Python API已启用： 偏好→ 将军→ 魔法→ 启用Python API
• Python 3.11+
• 紫外线 (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代码 在......下面

技能（可选）

通过安装代理技能 技能s.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          # Number of lines to read (-1 = all visible)
session_id: str = ""     # Target session (empty = active session)

运行命令

执行命令并捕获输出。等待输出稳定（2秒空闲）后返回。

command: str             # Shell command to execute
timeout: int = 30        # Max seconds to wait
session_id: str = ""

命令由保安进行分类：

• 安全 --只读命令(ls, pwd, git status, ...)
• 小心 --修改命令(mkdir, npm install, git push, ...)
• 危险 --破坏性命令(rm, sudo, kill, ...）--产生警告

send_text

在不自动按Enter键的情况下向会话发送文本。集 press_enter=true 提交。

text: str                # Text to send
press_enter: bool = false
session_id: str = ""

send_control

发送一个控制字符。

character: str           # One of: C, Z, D, L, ESCAPE, A, E, U, K, W, R
session_id: str = ""

watch_output

阻止，直到屏幕上出现正则表达式模式或超时。

pattern: str             # Regex pattern to match
timeout: int = 60        # Max seconds to wait
session_id: str = ""

管理会话

管理iTerm2会话。

action: str              # list | create | split | close | focus
session_id: str = ""     # Required for close/focus, optional for split
direction: str = "horizontal"  # horizontal | vertical (split only)

使用Claude代码

1.注册MCP服务器

添加 iterm2-agent 进入 mcpServers 对象在 ~/.claude.json:

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

替换 /path/to/iterm2-agent 使用您的实际克隆路径。该命令必须指向项目virtualenv中的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会话并尝试：

• “我的终端上现在有什么？”
• “跑 git status iTerm2“
• “拆分终端并在新窗格中运行测试”
• “启动开发服务器，并告诉我它什么时候准备好”
• “发送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           # Entry point: python -m iterm2_agent
│   ├── server.py             # FastMCP server with iTerm2 lifespan
│   ├── connection.py         # iTerm2Context, session resolution, screen reading
│   ├── security.py           # Command classification (SAFE/CAUTION/DANGEROUS)
│   └── tools/
│       ├── __init__.py       # Tool registration
│       ├── read_screen.py
│       ├── run_command.py
│       ├── send_text.py
│       ├── send_control.py
│       ├── watch_output.py
│       └── manage_session.py
├── tests/
│   ├── test_security.py      # Security guard unit tests
│   ├── test_read_screen.py   # Session resolution unit tests
│   ├── test_run_command.py   # Security integration tests
│   └── test_send_control.py  # Control character mapping tests
├── test_integration.py       # Live integration tests (requires iTerm2)
└── skills/iterm2-agent/
    └── SKILL.md              # Agent skill definition (skills.sh compatible)

测试

单元测试（无需iTerm2）：

uv pip install pytest pytest-asyncio
uv run pytest

实时集成测试（需要运行iTerm2）：

uv run python test_integration.py

许可证

麻省理工学院