🚀 MCP 终端项目文档
MCP 终端是一个强大的终端控制服务器，它借助 MCP 协议与大型语言模型集成，能够高效执行和管理终端命令，为用户带来便捷的操作体验。
🚀 快速开始
运行以下命令启动 MCP 终端服务器：
python -m src.mcp_terminal.stdiostream_server
✨ 主要特性
- 支持多种终端控制器，涵盖基于子进程、AppleScript 和 iTerm2 API 的控制器。
- 提供标准的 MCP 接口，方便与其他系统和服务进行交互。
- 具备可扩展架构，支持添加新的终端控制器和功能模块。
- 采用安全设计，拥有权限控制和命令过滤机制，保障运行环境的安全性。
📦 安装指南
先决条件
- 操作系统：Linux 或 macOS
- Python 版本：3.6 及以上版本
- 依赖管理工具：建议使用
pip进行包管理
使用 uv 安装
uv mcp-terminal@latest
Makefile 安装
make install
💻 使用示例
基础用法
# 基本使用
mcp-terminal execute_command --command "ls"
高级用法
# 带超时设置的命令执行
mcp-terminal execute_command --command "sleep 10" --timeout 5
📚 详细文档
配置 Claude Desktop
工具配置
在 Claude Desktop 中添加 MCP 终端工具：
{
"tools": {
"mcp-terminal": {
"type": "execute_command",
"config": {
"host": "localhost",
"port": "1234"
}
}
}
}
故障排除
常见问题
-
问题：无法连接到 MCP 终端服务器
- 解决方法：检查服务器是否在运行，并确认网络配置正确。
-
问题：命令执行超时
- 解决方法：增加命令的等待超时时间，或优化被调用命令的性能。
API 规范
执行命令
execute_command(
command: str,
wait_for_output: bool = True,
timeout: int = 10
) -> dict
参数说明：
command：要执行的终端命令。wait_for_output：是否等待命令输出，默认为 True。timeout：等待超时时间，单位为秒，默认为 10。
返回值：
{
"success": bool,
"output": str,
"error": str,
"return_code": int,
"warning": str
}
获取终端信息
get_terminal_info() -> dict
返回值：
{
"terminal_type": str,
"platform": str
}
安全注意事项
- 权限控制：仅允许受信任的来源连接到 MCP 终端服务器。
- 命令过滤：建议实现命令白名单或黑名单机制，防止未授权操作。
- 审计日志：定期审查执行的历史命令记录。
开发指南
目录结构
项目根目录/
├── mcp_terminal.py # 入口脚本
├── pyproject.toml # 项目配置与依赖管理
├── README.md # 用户文档
├── Makefile # 构建与运行脚本
└── src/
├── __init__.py
└── mcp_terminal/
├── stdio_server.py # 标准输入输出服务器实现
├── controllers/ # 终端控制器模块
│ ├── base.py # 基础接口定义
│ ├── subprocess.py # 子进程控制器实现
│ ├── applescript.py # AppleScript 控制器实现
│ └── iterm.py # iTerm2 API 控制器实现
└── tools/ # 工具模块
└── terminal_tools.py # 终端操作工具函数
贡献指南
- 代码规范：遵循 PEP8 编码规范。
- 测试要求：为新功能添加单元测试和集成测试。
- 提交流程：
- 提交前检查代码格式。
- 提交信息需包含相关变更说明。
📄 许可证
文档中未提及许可证相关信息。
📞 联系方式
- 邮件：support@mcp-terminal.com
- GitHub：https://github.com/mcpteam/mcp-terminal