金大哥 - iterm2-agent MCP 详情

article

README

🚀 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 | 读取可见终端内容和光标位置 | | run_command | 执行 shell 命令，等待输出稳定后返回结果 | | send_text | 向会话发送原始文本（可选择是否自动回车） | | send_control | 发送控制字符（如 Ctrl+C、Ctrl+Z、Ctrl+D 等） | | watch_output | 监控输出，直到匹配正则表达式模式 | | manage_session | 列出、创建、分割、关闭或聚焦会话 |

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 = ""

| 字符 | 按键 | 操作 | |-----------|-----|--------| | C | Ctrl+C | 中断 | | Z | Ctrl+Z | 挂起 | | D | Ctrl+D | 结束输入 | | L | Ctrl+L | 清屏 | | ESCAPE | Esc | 转义 | | A | Ctrl+A | 行首 | | E | Ctrl+E | 行尾 | | U | Ctrl+U | 删除整行 | | K | Ctrl+K | 删除到行尾 | | W | Ctrl+W | 删除单词 | | R | Ctrl+R | 反向搜索 |

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 许可证。

iterm2-agent