使用说明
MCP终端控制器
一种模型上下文协议（MCP）服务器，通过标准化接口实现安全的终端命令执行、目录导航和文件系统操作。
特性
- 命令执行：运行具有超时控制和全面输出捕获的终端命令
- 目录管理：使用直观的格式导航和列出目录内容
- 安全措施：针对危险命令和操作的内置防护措施
- 命令历史记录：跟踪和显示最近执行的命令
- 与跨平台支持：适用于基于Windows和UNIX的系统
- 文件操作：以行级精度读取、写入、更新、插入和删除文件内容
安装
通过Smithery安装
通过以下方式自动安装Claude Desktop的终端控制器 史密瑟里:
npx -y @smithery/cli install @GongRzhe/terminal-controller-mcp --client claude
先决条件
- Python 3.11+
- MCP兼容客户端（如Claude Desktop）
- 已安装UV/UVX（可选，适用于UVX方法）
方法1:PyPI安装（推荐）
直接从PyPI安装软件包：
pip install terminal-controller
或者，如果您更喜欢使用UV：
uv pip install terminal-controller
方法2：来源
如果您更喜欢从源代码安装：
-
克隆此存储库：
git clone https://github.com/GongRzhe/terminal-controller-mcp.git cd terminal-controller-mcp -
运行安装脚本：
python setup_mcp.py
客户端配置
克劳德桌面
有两种方法可以配置Claude Desktop以使用终端控制器：
选项1：使用UVX（推荐）
将此添加到您的Claude Desktop配置文件中：
"terminal-controller": {
"command": "uvx",
"args": ["terminal_controller"]
}
选项2：直接使用Python
"terminal-controller": {
"command": "python",
"args": ["-m", "terminal_controller"]
}
配置路径因操作系统而异：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json
光标
对于Cursor，使用与Claude Desktop类似的配置设置。
其他MCP客户端
对于其他客户端，请参阅其关于如何配置外部MCP服务器的文档。
用法
配置后，您可以使用自然语言通过MCP客户端与您的终端进行交互：
- “运行命令
ls -la在当前目录中” - “导航到我的文档文件夹”
- “显示下载目录的内容”
- “显示我最近的命令历史记录”
- “读取config.json的内容”
- 用“print（“Hello World”）”更新script.py文件中的第5行
- “从日志文件中删除第10-15行”
- “在文本文件的开头插入新行”
api参考
终端控制器提供以下MCP工具：
execute_command
执行终端命令并返回其结果。
参数：
command：要执行的命令行命令timeout：命令超时（秒）（默认值：30）
退货：
- 命令执行的输出，包括stdout、stderr和执行状态
get_command_history
获取最近的命令执行历史记录。
参数：
count：要返回的最近命令数（默认值：10）
退货：
- 格式化命令历史记录
get_current_directory
获取当前工作目录。
退货：
- 当前工作目录路径
change_directory
更改当前工作目录。
参数：
path：要切换到的目录路径
退货：
- 操作结果信息
list_directory
列出指定目录中的文件和子目录。
参数：
path：列表内容的目录路径（默认：当前目录）
退货：
- 目录内容列表，用目录和文件图标格式化
write_file
使用覆盖或附加选项将内容写入文件。
参数：
path：文件的路径content：要写的内容mode：写入模式（“重写”或“附加”，默认：“重写”）
退货：
- 操作结果信息，包括成功写入验证
read_file
使用可选的行选择从文件中读取内容。
参数：
path：文件的路径start_row：要读取的起始行（从0开始，可选）end_row：要读取的结束行（从0开始，包含在内，可选）
退货：
- 文件内容或选定行
insert_file_content
在文件中的特定行插入内容。
参数：
path：文件的路径content：要插入的内容row：要插入的行号（从0开始，可选）rows：要插入的行号列表（从0开始，可选）
退货：
- 操作结果信息
delete_file_content
从文件中删除特定行的内容。
参数：
path：文件的路径row：要删除的行号（从0开始，可选）rows：要删除的行号列表（从0开始，可选）
退货：
- 操作结果信息
update_file_content
更新文件中特定行的内容。
参数：
path：文件的路径content：要放置在指定行的新内容row：要更新的行号（从0开始，可选）rows：要更新的行号列表（从0开始，可选）
退货：
- 操作结果信息
安全考虑
终端控制器实施了多种安全措施：
- 防止长时间运行命令的超时控制
- 危险命令黑名单（rm-rf/，format，mkfs）
- 正确的错误处理和命令执行隔离
- 仅访问特别授予的命令和目录
局限性
- 只有在超时时间内完成的命令才会返回结果
- 默认情况下，服务器可以访问与运行它的用户相同的文件系统权限
- 由于终端界面的非交互式特性，一些交互式命令可能无法按预期工作
故障排除
如果您遇到问题：
- 检查你的Python版本是否为3.11或更高版本
- 验证您的Claude Desktop配置是否正确
- 尝试直接运行终端控制器以检查错误：
python -m terminal_controller - 对于UVX相关问题，请尝试：
uvx terminal_controller - 查看MCP客户端的日志以查找连接错误
贡献
欢迎投稿！请随时提交拉取请求。
许可证
麻省理工学院
