MCP 终端项目文档

项目简介

MCP 终端是一个终端控制服务器，允许通过 MCP 协议与大型语言模型集成，实现对终端命令的执行和管理。

特性

• 支持多种终端控制器：包括基于子进程、AppleScript 和 iTerm2 API 的控制器。
• 提供标准的 MCP 接口：便于与其他系统和服务进行交互。
• 可扩展架构：支持添加新的终端控制器和功能模块。
• 安全设计：具备权限控制和命令过滤机制，确保运行环境的安全性。

安装指南

先决条件

1. 操作系统：Linux 或 macOS
2. Python 版本：3.6 及以上版本
3. 依赖管理工具：建议使用 pip 进行包管理

使用 uv 安装

uv mcp-terminal@latest

Makefile 安装

make install

快速上手

启动服务器

运行以下命令启动 MCP 终端服务器：

python -m src.mcp_terminal.stdiostream_server

使用示例

执行终端命令：

# 基本使用
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  # 终端操作工具函数

贡献指南

1. 代码规范：遵循 PEP8 编码规范。
2. 测试要求：为新功能添加单元测试和集成测试。
3. 提交流程：
   • 提交前检查代码格式。
   • 提交信息需包含相关变更说明。

联系方式

• 邮件：support@mcp-terminal.com
• GitHub：https://github.com/mcpteam/mcp-terminal