MCP终端

Name: MCP终端
Author: sichang824

作者：sichang82419 星标更新：2025-05-16

安装使用来源：spider==github.com

项目介绍

MCP 终端

MCP 终端是一款基于MCP（模型上下文协议）的终端控制服务器，专门设计用于与大型语言模型（LLMs）和AI助手集成。它提供了一个标准化的接口，允许AI执行终端命令并获取输出结果。

English 中文

</div>

演示视频

特性

使用官方MCP SDK实现
支持多种终端控制器：
- ITerm2 控制器在 macOS 上使用 iTerm2 的 Python API 提供高级控制
- AppleScript 控制器使用 AppleScript 控制 macOS 上的终端应用
- 子进程控制器跨平台的通用终端控制方法
支持多种服务器模式：
- STDIO 模式通过标准输入/输出与客户端通信
- SSE 模式通过 Server-Sent Events 提供 HTTP API
提供多种工具：
- 终止工具执行命令并获取输出
- 文件工具执行文件操作（读写、追加、插入）
自动检测最优终端控制器
无缝集成到 Claude Desktop
支持 Docker 部署

安装

先决条件

Python 3.8+
uv 包管理工具

如果尚未安装 UV，可以使用以下命令进行安装：

# 在 macOS 上使用 Homebrew
brew install uv

# 在其他平台上
pip install uv

使用 UV 安装（推荐）

克隆仓库并使用 UV 安装依赖：

# 克隆仓库
git clone https://github.com/yourusername/mcp-terminal.git
cd mcp-terminal

# 创建虚拟环境并安装基础依赖
uv venv
source .venv/bin/activate  # 在 Windows 上使用 .venv\Scripts\activate
uv pip install -e .

# 如果需要 iTerm2 支持（仅限 macOS）
uv pip install -e ".[iterm]"

# 如果需要开发工具（测试、代码格式化等）
uv pip install -e ".[dev]"

注意：要使用 iTerm2 控制器，必须在 iTerm2 设置中启用 Python API。

打开 iTerm2 并依次进入 偏好设置 → 常规 → 魔法，勾选 启用 Python API 选项，如下图所示：

使用 Makefile 安装

我们提供了 Makefile 来简化常见操作：

# 安装基础依赖
make setup

# 安装 iTerm2 支持
make setup-iterm

# 安装开发依赖
make setup-dev

使用 Docker 安装

我们提供了 Docker 支持以快速部署 MCP 终端服务器：

# 构建 Docker 镜像
docker build -t mcp-terminal .

# 运行 Docker 容器（SSE 模式，端口 8000）
docker run -p 8000:8000 mcp-terminal

或者使用 docker-compose：

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

使用说明

运行 MCP 终端服务器

有多种方式启动服务器：

# 使用 Python 直接运行（默认使用 stdio 模式和自动检测终端控制器）
python mcp_terminal.py

# 使用 Makefile 运行（stdio 模式）
make run-stdio

# 使用 Makefile 运行（SSE 模式）
make run-sse

# 使用指定控制器
make run-iterm     # 使用 iTerm2 控制器
make run-applescript  # 使用 AppleScript 控制器
make run-subprocess   # 使用子进程控制器

使用 Docker 运行

使用 Docker 运行 MCP 终端服务器（默认 SSE 模式和子进程控制器）：

# 直接运行
docker run -p 8000:8000 mcp-terminal

# 使用自定义端口
docker run -p 9000:8000 mcp-terminal

# 挂载当前目录（可访问本地文件）
docker run -p 8000:8000 -v $(pwd):/workspace mcp-terminal

默认配置：

服务器模式：SSE
主机：0.0.0.0（允许远程连接）
端口：8000
控制器：子进程（适用于容器环境）

可以通过修改 Dockerfile 或 docker-compose.yml 文件来自定义配置。

将 Docker 容器作为 MCP 服务配置在 Claude 或其他 AI 中

可以在 Claude 或其他支持 MCP 的 AI 中配置 Docker 容器作为 MCP 服务，使 Claude 或其他 AI 能够直接使用容器化工具。以下是在 Claude 配置文件中使用 Docker 容器作为 MCP 服务的示例：

{
  "mcp": {
    "servers": {
      "terminal": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "--mount",
          "type=bind,src=${workspaceFolder},dst=/workspace",
          "mcp-terminal",
          "mcp-terminal",
          "--mode",
          "sse",
          "--host",
          "0.0.0.0",
          "--port",
          "8000"
        ]
      }
    }
  }
}

此配置允许：

通过 Docker 容器隔离工具执行环境
不需要在本地安装特定工具即可使用其功能
在不同环境中保持一致的工具版本和配置
使用 ${workspaceFolder} 变量将当前工作目录挂载到容器中
使用 --rm 确保容器在使用后被自动删除，以保持干净的环境

可以根据需要定义多个不同的 MCP 服务容器，每个容器专用于特定的功能。

Claude Desktop 集成配置示例

以下是 Claude Desktop 配置示例：

{
  "mcpServers": {
    "terminal": {
      "command": "/Users/ann/Workspace/mcp-terminal/.venv/bin/python",
      "args": [
        "/Users/ann/Workspace/mcp-terminal/mcp_terminal.py",
        "--controller",
        "subprocess"
      ]
    }
  }
}

命令行选项

服务器支持多种命令行选项：

python mcp_terminal.py --help

主要选项：

--controller 或 -c 指定终端控制器类型（auto, iterm, apple script, subprocess）
--mode 或 -m：指定服务器模式（stdio, sse）
--host：指定 SSE 模式的主机地址
--port 或 -p：指定 SSE 模式的端口
--log-level 或 -l：指定日志级别

与 Claude Desktop 集成

MCP 终端可以无缝集成到 Claude Desktop，为 Claude 提供终端控制能力。

配置步骤

启动 MCP 终端服务器（在 STDio 模式下）：
```
# 在一个终端窗口中运行
make run-stdio
```
配置 Claude Desktop 使用 MCP 服务器：

打开 Claude Desktop，然后：
- 点击设置图标（通常位于右上角）
- 导航到“扩展”或“工具”标签
- 启用“自定义工具”功能
- 添加 MCP 终端配置：
  - 工具名称：终端
  - 工具路径：输入 mcp_terminal.py 的完整路径
  - 使用 STDio 模式：勾选复选框
  - 保存配置
测试集成：

在与 Claude 的对话中，现在可以请求 Claude 执行终端命令，例如：
- 请列出我的主目录中的文件
- 检查我当前的 Python 版本
- 创建一个新的目录，并将当前日期写入文件

故障排除

如果集成不正常工作：

确保 MCP 终端服务器正在运行
检查日志输出以查找错误
验证 Claude Desktop 的工具配置是否正确
尝试重新启动 Claude Desktop 和 MCP 终端服务器

API 规范

MCP 终端提供以下 MCP 函数：

execute_command

执行终端命令并获取输出结果。

参数：

command (字符串)：要执行的命令
wait_for_output (布尔值，可选)：是否等待并返回命令输出，默认为 true
timeout (整数，可选)：等待输出的超时时间（秒），默认为 10

success (布尔值)：命令是否成功执行
output (字符串，可选)：命令的输出结果
error (字符串，可选)：如果命令失败，则返回错误消息
return_code (整数，可选)：命令的返回码
warning (字符串，可选)：警告信息

get_terminal_info

获取终端信息。

参数：无

terminal_type (字符串)：正在使用的终端类型
platform (字符串)：运行平台

file_modify

向文件中写入、追加或插入内容。

参数：

filepath (字符串)：文件路径
content (字符串)：要写入的内容
mode (字符串，可选)：写入模式，可选值为 "overwrite"、"append" 或 "insert"，默认为 "overwrite"
position (整数，可选)：使用 "insert" 模式时的插入位置
create_dirs (布尔值，可选)：如果目录不存在，是否创建目录，默认为 true

success (布尔值)：操作是否成功
error (字符串，可选)：如果操作失败，则返回错误消息
filepath (字符串)：操作的文件路径
details (对象，可选)：附加的操作详情

安全注意事项

MCP 终端允许执行任意终端命令，这可能会带来安全风险。在生产环境中使用时，应：

限制服务器只接受来自可信来源的连接
考虑实施命令白名单或黑名单
对命令执行进行定期审计
在专用账户下运行服务器并限制其权限

开发

目录结构

mcp-terminal/
├── mcp_terminal.py            # 入口点脚本
├── pyproject.toml             # 项目配置和依赖
├── README.md                  # 项目文档
├── Makefile                   # 构建和运行命令
├── Dockerfile                 # Docker 构建配置
├── docker-compose.yml         # Docker Compose 配置
├── src/
│   ├── __init__.py
│   └── mcp_terminal/
│       ├── __init__.py
│       ├── server.py          # 主服务器实现
│       ├── controllers/
│       │   ├── __init__.py    # 控制器工厂和导入
│       │   ├── base.py        # 基础控制器接口
│       │   ├── subprocess.py  # 通用子进程控制器
│       │   ├── applescript.py # AppleScript 控制器
│       │   └── iterm.py       # iTerm2 API 控制器
│       └── tools/
│           ├── __init__.py
│           ├── terminal.py    # 终端操作工具
│           └── file.py        # 文件操作工具
└── tests/                     # 测试目录
    ├── __init__.py
    └── test_subprocess_controller.py

运行测试

# 使用 pytest 运行所有测试
make test

# 或者直接使用 pytest
pytest tests/

代码格式化

# 检查代码格式
make lint

# 自动格式化代码
make format

贡献

欢迎贡献！请遵循以下步骤：

分叉仓库
创建功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m 'Add some amazing feature'）
推送到分支（git push origin feature/amazing-feature）
提交 Pull Request

许可证

本项目采用 MIT 许可证 - 详见LICENSE文档。