iterm-mcp

一个模型上下文协议服务器，提供对您的 iTerm 会话的访问权限。

功能特性

高效使用令牌： iterm-mcp 让模型仅能查看其感兴趣的输出内容。通常情况下，即使对于长时间运行的命令，模型也只希望看到最后几行输出。

自然集成： 您与模型共享 iTerm 窗口。您可以就屏幕上显示的内容提问，也可以将任务委托给模型，并观察它逐步完成每一步操作。

完整的终端控制与 REPL 支持： 模型可以启动并交互式地使用 REPL，同时还能发送控制字符，如 Ctrl+C、Ctrl+Z 等。

依赖轻量： iterm-mcp 构建时尽量减少了依赖项，并可通过 npx 直接运行。它被设计为易于添加到 Claude Desktop 及其他 MCP 客户端中，应该能够即装即用。

安全注意事项

• 用户有责任安全地使用该工具。
• 无内置限制：iterm-mcp 不会对执行的命令进行安全性评估。
• 模型可能会表现出意想不到的行为。用户应密切关注其活动，并在必要时及时终止操作。
• 对于多步骤任务，如果模型偏离预期路径，您可能需要中断其操作。建议从较小且目标明确的任务开始，逐步熟悉模型的行为模式。

工具

• write_to_terminal - 向当前激活的 iTerm 终端写入内容，常用于执行命令。返回该命令产生的输出行数。
• read_terminal_output - 从当前激活的 iTerm 终端读取指定行数的输出内容。
• send_control_character - 向当前激活的 iTerm 终端发送控制字符。

系统要求

• 必须运行 iTerm2
• Node.js 版本 18 或更高

安装

若要与 Claude Desktop 配合使用，请添加以下服务器配置：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%/Claude/claude_desktop_config.json

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

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 iTerm：

npx -y @smithery/cli install iterm-mcp --client claude

开发

安装依赖：

yarn install

构建服务器：

yarn run build

若需开发并启用自动重新构建：

yarn run watch

调试

由于 MCP 服务器通过标准输入输出进行通信，调试可能会比较困难。我们推荐使用 MCP Inspector，它作为包脚本提供：

yarn run inspector
yarn debug <command>

Inspector 将为您提供一个 URL，以便在浏览器中访问调试工具。

iterm-mcp 快速上手指南

iterm-mcp 是一个基于 Model Context Protocol (MCP) 的服务器工具，它允许 AI 模型直接访问和控制你的 iTerm2 终端会话。你可以让 AI 查看屏幕输出、执行命令、与 REPL 交互，甚至发送控制字符（如 Ctrl+C）。

环境准备

在开始之前，请确保满足以下系统要求和依赖：

• 操作系统：macOS（必须运行 iTerm2 终端模拟器）。
• Node.js：版本 18 或更高。
  • 检查版本命令：node -v
• 客户端：已安装并配置好支持 MCP 的客户端（如 Claude Desktop）。

安装步骤

你可以通过手动配置或自动化工具将 iterm-mcp 集成到 Claude Desktop 中。

方式一：手动配置（推荐）

编辑 Claude Desktop 的配置文件，添加 iterm-mcp 服务器配置。

1. 打开配置文件：

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

2. 在 mcpServers 对象中添加以下配置：

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

3. 保存文件并重启 Claude Desktop。

方式二：通过 Smithery 自动安装

如果你希望自动化安装过程，可以使用 Smithery CLI：

npx -y @smithery/cli install iterm-mcp --client claude

基本使用

安装完成后，重启 Claude Desktop 即可在对话中使用该工具。AI 将能够调用以下核心功能：

• write_to_terminal: 向当前活跃的 iTerm 窗口写入内容（通常用于运行命令）。
• read_terminal_output: 读取指定行数的终端输出。
• send_control_character: 发送控制字符（如 ctrl-c, ctrl-z）。

使用示例

你可以在对话框中直接向 AI 发出自然语言指令，例如：

“请在当前的 iTerm 窗口中运行 ls -la，然后告诉我最后 5 行输出是什么。”

“启动一个 Python REPL，帮我计算 123 * 456，然后退出。”

“如果当前的命令卡住了，请发送 Ctrl+C 中断它。”

⚠️ 安全提示

• 无内置限制：iterm-mcp 不会评估命令的安全性，所有操作均由用户负责。
• 实时监控：AI 可能会执行意外操作。在执行多步任务时，请密切监控终端活动，并在必要时手动中断。
• 从小任务开始：建议先尝试简单的单步任务，熟悉模型行为后再委托复杂操作。