iterm-mcp

作为开发者，终端是我们最频繁打交道的工具之一。但你是否曾经遇到过这样的情况：正在构思一个复杂的命令，或者需要向新手解释某个命令行操作，却希望有 AI 能直接在终端里帮你执行？iterm-mcp 正是为此而生。它让 AI 助手能够直接操控你的 iTerm2 终端——执行命令、读取输出、甚至与正在运行的进程交互，将终端的自动化能力提升到了一个全新的层次。

项目基本信息

一、项目介绍

iterm-mcp 是一个专门为 macOS 上的 iTerm2 终端模拟器设计的 MCP 服务器。它通过模型上下文协议，将终端会话的控制权赋予 AI 助手，让 AI 能够像人类用户一样执行命令、查看输出，并与交互式终端程序进行通信。

核心工具

该服务器提供了一套覆盖终端操作全流程的工具：

• launch：启动一个新的 iTerm2 窗口或标签页，并可选择在其中执行初始命令。
• exec：在指定终端会话中执行命令，并返回执行结果和输出。
• write：向指定终端会话的标准输入写入文本，模拟用户键盘输入。
• read：读取指定终端会话的当前屏幕内容。
• list_sessions：列出当前所有活跃的 iTerm2 会话。
• close_session：关闭指定的终端会话。
• get_current_ssh_path：获取当前 SSH 会话的远程路径信息（适用于远程开发场景）。

通过这些工具的组合，AI 助手能够完成从简单的命令执行到复杂的交互式终端操作等一系列任务，真正成为你在终端工作中的“数字同事”。

二、核心优势

深度终端集成

与那些只能执行单个命令并返回结果的简单方案不同，iterm-mcp 能够维持与终端会话的持久连接。这意味着 AI 可以执行一系列相关命令、处理命令间的状态依赖，甚至与 vim、ssh 等交互式程序进行通信。

熟悉的终端环境

所有操作都在你最熟悉的 iTerm2 终端中进行。你可以亲眼看到 AI 执行的每一条命令及其输出，这一透明性让你对 AI 的操作始终保持完全可见和可控。

交互式程序支持

write 工具的存在，让 AI 能够与需要持续交互的程序进行通信。无论是 SSH 连接后的密码输入、数据库客户端的查询操作，还是文本编辑器的使用，AI 都能模拟你的键盘输入。

远程开发友好

对于经常通过 SSH 连接到远程服务器的开发者，get_current_ssh_path 工具能提供当前会话的远程路径信息，让 AI 在处理远程文件时保持路径的准确性。

开源与可扩展

项目采用 MIT 协议，代码完全开源。TypeScript 的代码结构清晰，依赖明确，为希望进行二次开发或学习 MCP 服务器构建的开发者提供了优秀的参考范例。

三、适用场景

AI 辅助的命令行操作

当你忘记某个命令的精确语法，或者需要组合多个命令完成复杂操作时，可以直接告诉 AI 你的需求，它会帮你执行正确的命令并展示结果。

自动化开发环境设置

让 AI 帮你一键完成新项目的开发环境初始化：克隆仓库、安装依赖、配置数据库、启动服务——全部在同一个终端会话中完成。

远程服务器管理与运维

通过 SSH 连接到远程服务器后，AI 可以帮你监控系统状态、排查日志错误、批量执行管理任务，并始终保持会话上下文。

技术演示与教学

在进行技术分享或教学时，你可以让 AI 实时执行命令并展示输出，让演示过程更加流畅，避免手动输入时的拼写错误。

交互式程序操控

需要频繁与某个命令行交互程序（如数据库 CLI、REPL 环境）交互时，AI 可以代替你进行繁琐的输入和响应处理。

四、安装教程

环境要求

启用 iTerm2 Python API

在 iTerm2 中：

1. 打开 iTerm2 -> Preferences。
2. 选择 General 选项卡。
3. 找到 Magic 部分。
4. 勾选 "Enable Python API"。

在 Claude Desktop 中配置

编辑 Claude Desktop 的配置文件（macOS）：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "iterm-mcp": {
      "command": "npx",
      "args": ["-y", "@ferrislucas/iterm-mcp"]
    }
  }
}

保存文件后，完全退出并重启 Claude Desktop，配置即生效。

本地开发安装

1. 克隆仓库

   git clone https://github.com/ferrislucas/iterm-mcp.git
   cd iterm-mcp

2. 安装依赖

   npm install

3. 构建项目

   npm run build

4. 在 Claude Desktop 中配置
   将 command 指向你本地的 node 和构建后的文件路径。

五、使用示例

配置完成后，你可以在 AI 客户端中使用自然语言指挥 AI 完成终端操作。

示例一：快速启动项目

用户：帮我打开一个新的 iTerm2 窗口，进入 /Users/me/projects/my-app 目录，然后运行 npm start。

AI 的操作:
AI 会调用 launch 工具，创建一个新终端，并依次执行 cd /Users/me/projects/my-app 和 npm start 命令。

示例二：执行命令并分析输出

用户：在我的终端里运行 git log --oneline -10，然后告诉我最近提交的主题都是什么。

AI 的操作:
AI 调用 exec 执行 git log 命令，从返回的输出中分析并总结最近的提交内容。

示例三：交互式程序操控

用户：帮我在终端里通过 SSH 连接到 server.example.com，输入密码，然后查看磁盘使用情况。

AI 的操作:
AI 会依次调用 exec 执行 SSH 命令，然后用 write 工具输入密码，最后再次调用 exec 执行 df -h 命令。

示例四：查看当前终端状态

用户：列出我当前所有打开的 iTerm2 窗口和标签页，然后读取第一个窗口的当前内容。

AI 的操作:
AI 会先调用 list_sessions 获取所有会话列表，然后调用 read 读取指定会话的屏幕内容。

六、常见问题

问：配置后 AI 提示无法连接到 iTerm2 怎么办？

答：请检查以下几点：

1. 确认已启用 Python API：在 iTerm2 的 Preferences -> General -> Magic 中，确保 "Enable Python API" 已勾选。
2. 确认 iTerm2 正在运行：MCP 服务器需要连接到已开启的 iTerm2 实例。
3. 检查 macOS 权限：macOS 可能需要授予 iTerm2 和 Claude Desktop 相关的自动化权限，可以到“系统偏好设置” -> “安全性与隐私” -> “辅助功能”中检查。

问：这个工具只支持 macOS 吗？

答：是的，iterm-mcp 专门为 macOS 上的 iTerm2 终端模拟器设计，不支持 Windows Terminal 或其他平台的终端工具。这是因为 iTerm2 提供了强大的 Python API，使得外部程序能够与其进行深度交互。

问：AI 可以在 SSH 连接的远程终端中执行命令吗？

答：可以。通过 exec 执行 SSH 连接命令后，后续的 exec 和 write 调用都会在远程会话的上下文中进行。你还可以使用 get_current_ssh_path 工具查询当前的远程路径。

问：我的终端输出包含敏感信息，AI 能看到吗？

答：是的。read 工具会读取终端屏幕上的所有内容，包括密码、密钥等敏感信息。请确保在 AI 读取终端输出前，屏幕上没有你不希望被处理的信息。可以先用 clear 命令清屏，或者提前退出敏感会话。

七、总结

iterm-mcp 是一个将 AI 能力延伸到终端操作领域的创新工具。它充分利用了 iTerm2 的 Python API 和 MCP 协议的标准化接口，让 AI 助手能够像一个熟练的开发者一样操控终端——执行命令、管理会话、甚至与交互式程序通信。

对于经常与终端打交道的 macOS 开发者来说，这个工具不仅能减少重复性的命令输入，更能在你遇到障碍时提供实时的命令建议和执行。它是“AI 辅助开发”在终端环境中的一次具体且实用的落地，让开发者与 AI 的协作变得更加紧密和自然。花几分钟完成配置，你会感受到那种“有个懂命令行的助手随时待命”的便利与高效。