内容
# mcp-server-iterm2
[](https://github.com/r6e/mcp-server-iterm2/actions/workflows/ci.yml)
[](https://pypi.org/project/mcp-server-iterm2/)
[](https://pypi.org/project/mcp-server-iterm2/)
一款 Model Context Protocol (MCP) 服务器，用于向代理暴露 iTerm2 以进行**观察**和**非破坏性注释**。代理可以检查会话并装饰它们（徽章、标题、标签颜色、用户变量、通知），但不能注入按键、关闭或生成会话，或以其他方式更改用户的操作环境。
## 安装
配置您的MCP客户端（例如Claude Desktop，Claude Code）：
```json
{
"mcpServers": {
"iterm2": {
"command": "uvx",
"args": ["mcp-server-iterm2"]
}
}
}
```
需要安装 macOS、iTerm2 和 [`uv`](https://docs.astral.sh/uv/)。
## 首次运行
在首次调用时，iTerm2 会提示您授权脚本的 API 访问权限。请批准它。后续运行将是静默的。
如果您之前拒绝了访问权限：iTerm2 → 首选项 → 常规 → 魔术 → 启用“Python API”并从拒绝列表中删除 `mcp-server-iterm2`。
## 工具
### 读取
| 工具 | 描述 |
| --- | --- |
| `list_sessions` | 窗口 → 标签 → 会话的树形结构，以及一个顶级 `buried_sessions` 列表。 |
| `get_session_info` | 标题、工作目录、配置文件、徽章、尺寸、TTY |
| `get_screen_contents` | 可见缓冲区 + 光标位置 |
| `get_scrollback` | 最后 N 行（默认为 200，最大 5000） |
| `get_recent_output` | 光标标记后的输出（基于光标的分页） |
| `get_selection` | 当前选定的文本 |
| `get_variable` | 读取一个变量，格式为完全限定名称（例如 `session.path`、`user.badge`） |
| `list_profiles` | 按名称和 GUID 列出的可用配置文件 |
### 写入（非破坏性）
| 工具 | 描述 |
| --- | --- |
| `set_badge` | 设置会话徽章文本 |
| `set_title` | 重写会话标题 |
| `set_tab_color` | 为标签着色（RGB 0-255） |
| `set_user_variable` | 设置 `user.*` 会话变量 |
| `post_notification` | 发布 macOS 通知横幅 |
每个会话目标工具都接受一个可选的 `session_id`。如果省略，服务器将使用其环境中的 `$ITERM_SESSION_ID` — 当代理在 iTerm2 内运行时，这会自动生效。
## 渲染说明
- **徽章：** 要使 `set_badge` 显示任何内容，您的 iTerm2 配置文件的徽章格式必须包含 `\(user.badge)`。在 iTerm2 → 配置文件 → 常规 → 徽章中配置。
- **标题：** `set_title` 重写是否生效取决于配置文件的“允许终端应用程序更改标题”和“标题组件”设置。服务器始终设置重写；iTerm2 控制渲染。
- **标签颜色：** `set_tab_color` 会写入旧版标签颜色以及浅色和深色模式的变体，以便无论配置文件是否启用分色，着色都会生效。
- **通知：** 通过 `osascript` 路由到 macOS。确保在系统设置中允许 Terminal/iTerm2 通知，如果横幅不出现。
## 设计上排除的内容
出于安全考虑，以下内容未被暴露：`send_text`/按键注入、关闭或生成会话/标签/窗口、拆分窗格、焦点更改、广播输入。
## 安全模型
安装此服务器后，任何使用它的 MCP 客户端都可以广泛读取您的 iTerm2 会话（屏幕内容、回滚、 工作目录、变量）并具有有限的写入访问权限（徽章、标题、标签颜色、`user.*` 变量、macOS 通知）。读取工具可以捕获屏幕上可见的密码；写入工具可以伪造标题和通知。完整的威胁模型和报告流程位于 [SECURITY.md](SECURITY.md)。
## 开发
```bash
uv sync
uv run pytest tests/unit # 122 个单元测试
uv run ruff check . # 检查代码风格
uv run ruff format --check . # 检查代码格式
uv run ty check src # 类型检查
```
集成测试 (`pytest -m integration`) 和烟雾测试脚本 (`scripts/smoke.py`) 需要在 iTerm2 会话中运行。有关完整的开发指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)，有关各个部分的架构，请参阅 [ARCHITECTURE.md](ARCHITECTURE.md)。
## API 稳定性
该项目遵循 [语义版本控制](https://semver.org/)。当前版本位于 `0.x` 系列；随着工具表面根据实际反馈稳定，预计在次要版本之间进行模式改进。从 `1.0` 开始，以下内容将成为稳定契约的一部分 — 破坏任何一个都需要进行重大更新：
- **工具名称和工具集。** 名称和工具的删除是稳定的；可以在次要版本中添加新工具。
- **工具参数名称和类型。** 可以在次要版本中添加新的可选参数；现有的参数名称、类型和必需性不会更改。
- **顶级响应键和值类型。** 可以在次要版本中添加新键；现有的键及其类型不会更改。
- **错误信封形状。** `MCPIterm2Error` 子类通过 `to_error_text` 提供可操作的文本；未知异常会归结为 `Internal error: <ExceptionClass>`。调用者可以匹配此信封。
不属于稳定界面的内容：
- 内部 Python 模块 (`server.py`、`connection.py`、`tools/*`、`errors.py`、`output_cursor.py`) — 这些是实现细节。
- `get_recent_output` 的特定光标有效载荷编码。将光标视为不透明的；返回服务器返回的内容。
- iTerm2 SDK 和 macOS 版本兼容性窗口 — 这些跟随上游并且可能在次要版本中更改。
## 文档
- [ARCHITECTURE.md](ARCHITECTURE.md) — 模块布局、生命周期、数据流
- [CONTRIBUTING.md](CONTRIBUTING.md) — 开发设置、质量门控、PR 流程
- [SECURITY.md](SECURITY.md) — 威胁模型和漏洞报告方式
- [CHANGELOG.md](CHANGELOG.md) — 版本历史
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — 社区标准
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
