AI导哈

iTerm2终端内容读取服务

一个允许AI助手读取iTerm2终端内容的MCP服务器，支持查看终端窗口、标签页和面板的工作目录及运行任务。

  • by sumchattering
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 sumchattering/iterm2-mcp-server

使用说明

iTerm2 MCP服务器

一个MCP（模型上下文协议）服务器，允许像克劳德这样的人工智能助手读取iTerm2终端窗格的内容。这使AI助手能够看到其他终端窗口和选项卡中发生的事情。

特征

  • 列出所有窗格：查看所有打开的iTerm2窗口、选项卡和窗格及其工作目录和正在运行的作业
  • 阅读窗格内容：从任何窗格获取屏幕缓冲区文本
  • 当前窗格检测：自动检测服务器正在哪个窗格中运行
  • 状态检查：验证iTerm2 Python API是否已正确配置

先决条件

  1. macOS 安装了iTerm2
  2. Node.js >= 18.0.0
  3. Python 3 随着 iterm2 包裹：
    pip install iterm2
  4. iTerm2 Python API已启用:
    • 打开iTerm2>设置（Cmd+，）
    • 首选 通用 > 魔法
    • 检查 启用Python API
    • 重新启动iTerm2

安装

使用npx（推荐）

npx iterm2-mcp-server

全球安装

npm install -g iterm2-mcp-server
iterm2-mcp-server

配置

克劳德桌面

添加到您的Claude Desktop配置文件(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "iterm2": {
      "command": "npx",
      "args": ["iterm2-mcp-server"]
    }
  }
}

克劳德代码

使用CLI添加MCP服务器：

claude mcp add --scope user iterm2 -- npx github:sumchattering/iterm2-mcp-server

这将在全局范围内安装它，以便它在您的所有项目中都可用。您可以验证它是否正常工作：

claude mcp list

您应该看到： iterm2: npx github:sumchattering/iterm2-mcp-server - ✓ Connected

可用工具

iterm2_list_panes

列出所有iTerm2窗口、选项卡和窗格及其简写ID、名称、工作目录和正在运行的作业。

iterm2_read_pane

读取特定窗格的屏幕缓冲区内容。

参数：

  • session_id （必填）：窗格ID使用简写，如 t3p1 （选项卡3，窗格1）或 w1t3p1

iterm2_send_text

将文本或命令发送到iTerm2窗格，就像用户键入的一样。

参数：

  • session_id （必填）：窗格ID（例如。， t3p1)
  • text （必填）：要发送的文本或命令
  • newline （可选，默认值：true）：文本后是否按Enter键

iterm2_send_control_character

将控制字符（如Ctrl+C、Ctrl+D、Ctrl+Z或Ctrl+L）发送到iTerm2窗格。

参数：

  • session_id （必填）：窗格ID（例如。， t3p1)
  • control （必填）： c （Ctrl+C）， d （Ctrl+D）， z （Ctrl+Z）， l （Ctrl+L）

iterm2_split_pane

水平或垂直拆分iTerm2窗格，创建新窗格。

参数：

  • session_id （必填）：要拆分的窗格ID（例如。， t3p1)
  • vertical （可选，默认值：false）：如果为true，则垂直拆分（并排）

iterm2_current_pane

获取有关运行Claude Code的当前iTerm2窗格的信息。

iterm2_status

检查iTerm2 Python API是否已正确配置并准备好使用。

iterm2_enable_api

在首选项中启用iTerm2 Python API。注意：启用后必须重新启动iTerm2。

窗格ID

窗格使用与iTerm2的UI匹配的简写ID进行标识（基于1的索引）：

  • t3p1 -选项卡3，窗格1（假定窗口1）
  • t3p2 -选项卡3，窗格2
  • w1t3p1 -窗口1，选项卡3，窗格1（显式窗口）
  • w2t1p1 -窗口2，选项卡1，窗格1

使用 iterm2_list_panes 查看所有可用窗格及其ID。

使用Claude代码

安装后，Claude Code可以查看您的终端窗格并与之交互。以下是使用它的有效方法：

询问窗格

  • “选项卡3中有什么？”-Claude将阅读选项卡3的内容
  • “你旁边的窗格中正在运行什么？”-克劳德可以识别相邻的窗格
  • “显示我的所有终端选项卡”-列出所有窗格及其简写ID
  • “我的服务器的输出是什么？”-Claude可以查找并读取服务器输出

在其他窗格中运行命令

  • “跑 npm test in t3p1“-将命令发送到特定窗格
  • “停止选项卡4中的进程”-发送Ctrl+C中断
  • “清除t2p1中的终端”-发送Ctrl+L

使用多个窗格

  • “拆分我的终端并在新窗格中运行开发服务器”
  • “我的其他终端显示了哪些错误？”
  • “比较选项卡2和选项卡3中的输出”

有效查询的技巧

  1. 具体说明位置：“选项卡3”或“t3p1”比“其他终端”更清晰
  2. 参考窗格列表：如果你不确定布局，请让克劳德先列出窗格
  3. 使用相对参考：“您旁边的窗格”或“左侧的选项卡”也适用

故障排除

“连接失败”错误

  1. 确保iTerm2正在运行
  2. 验证Python API是否已启用：iTerm2>设置>常规>魔术>启用Python API
  3. 重新启动iTerm2 启用API后（Cmd+Q，然后重新打开）

“未安装iterm2模块”

安装Python包：

pip install iterm2

“未在iTerm2会话中运行”

MCP服务器需要从iTerm2终端内启动，才能进行当前窗格检测。

运作原理

此MCP服务器使用 iTerm2 Python API 通过WebSocket连接与iTerm2通信。服务器：

  1. 通过MCP接收来自AI助手的工具调用
  2. 执行使用 iterm2 图书馆
  3. 将格式化的结果返回给助手

发展

# Clone the repository
git clone https://github.com/sumchattering/iterm2-mcp-server.git
cd iterm2-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

许可证

MIT许可证-请参阅 许可证 了解详情。

贡献

欢迎投稿！请随时提交拉取请求。

未来改进

未来版本正在考虑以下功能。欢迎反馈！

  • 创建选项卡/窗口: iterm2_create_tab 和 iterm2_create_window 工具
  • 关闭窗格: iterm2_close_pane 以编程方式关闭窗格的工具
  • 焦点窗格: iterm2_focus_pane 将特定窗格置于前台
  • 等待提示: iterm2_wait_for_prompt 等待命令执行完毕
  • 设置窗格标题：能够为窗格设置自定义标题
  • 性能优化：持久化Python进程，而不是按请求生成

相关 MCP