mcp-terminal

MCP Terminal

特性

• 使用官方 MCP SDK 实现

• 支持多种终端控制器：
• iTerm2 控制器：在 macOS 上使用 iTerm2 的 Python API 提供高级控制
• AppleScript 控制器：在 macOS 上使用 AppleScript 控制 Terminal 应用
• Subprocess 控制器：在所有平台上通用的终端控制方式

• 支持多种服务器模式：
• STDIO 模式：通过标准输入/输出与客户端通信
• SSE 模式：通过 Server-Sent Events 提供 HTTP API

• 自动检测最佳终端控制器

• 与 Claude Desktop 无缝集成

安装

先决条件

• Python 3.8+

• uv 包管理工具

使用 uv 安装（推荐）

使用 Makefile 安装

使用方法

运行 MCP 终端服务器

Claude Desktop

命令行选项

• --controller 或 -c：指定终端控制器类型（auto, iterm, applescript, subprocess）

• --mode 或 -m：指定服务器模式（stdio, sse）

• --host：指定 SSE 模式主机地址

• --port 或 -p：指定 SSE 模式端口

• --log-level 或 -l：指定日志级别

与 Claude Desktop 集成

配置步骤

1. 启动 MCP Terminal 服务器（以 stdio 模式）：

2. 配置 Claude Desktop 使用 MCP 服务器：
打开 Claude Desktop，然后：
• 点击设置图标（通常在右上角）
• 导航到"扩展"或"工具"选项卡
• 启用"自定义工具"功能
• 添加 MCP Terminal 的配置：
• 工具名称：Terminal
• 工具路径：输入 mcp_terminal.py 的完整路径
• 使用 stdio 模式：勾选
• 保存配置

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

故障排除

1. 确保 MCP Terminal 服务器正在运行

2. 检查日志输出以查找错误

3. 验证 Claude Desktop 的工具配置是否正确

4. 尝试重启 Claude Desktop 和 MCP Terminal 服务器

API 规范

execute_command

• command (string)：要执行的命令

• wait_for_output (boolean, 可选)：是否等待并返回命令输出，默认为 true

• timeout (integer, 可选)：等待输出的超时时间（秒），默认为 10

• success (boolean)：命令是否成功执行

• output (string, 可选)：命令的输出结果

• error (string, 可选)：如果命令失败，返回错误信息

• return_code (integer, 可选)：命令的返回代码

• warning (string, 可选)：警告信息

get_terminal_info

• terminal_type (string)：正在使用的终端类型

• platform (string)：运行平台

安全考虑

1. 限制服务器只接受来自受信任来源的连接

2. 考虑实现命令白名单或黑名单

3. 定期审计执行的命令

4. 在专用账户下运行服务器，限制其权限

开发

目录结构

运行测试

代码格式化

贡献

1. Fork 仓库

2. 创建功能分支 (git checkout -b feature/amazing-feature)

3. 提交更改 (git commit -m 'Add some amazing feature')

4. 推送到分支 (git push origin feature/amazing-feature)

5. 提交 Pull Request

许可证