Terminal Control

🚀 MCP 終端項目文檔

MCP 終端是一個強大的終端控制服務器，它藉助 MCP 協議與大型語言模型集成，能夠高效執行和管理終端命令，為用戶帶來便捷的操作體驗。

🚀 快速開始

運行以下命令啟動 MCP 終端服務器：

python -m src.mcp_terminal.stdiostream_server

✨ 主要特性

• 支持多種終端控制器，涵蓋基於子進程、AppleScript 和 iTerm2 API 的控制器。
• 提供標準的 MCP 接口，方便與其他系統和服務進行交互。
• 具備可擴展架構，支持添加新的終端控制器和功能模塊。
• 採用安全設計，擁有權限控制和命令過濾機制，保障運行環境的安全性。

📦 安裝指南

先決條件

1. 操作系統：Linux 或 macOS
2. Python 版本：3.6 及以上版本
3. 依賴管理工具：建議使用 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  # 終端操作工具函數

貢獻指南

1. 代碼規範：遵循 PEP8 編碼規範。
2. 測試要求：為新功能添加單元測試和集成測試。
3. 提交流程：
   • 提交前檢查代碼格式。
   • 提交信息需包含相關變更說明。

📄 許可證

文檔中未提及許可證相關信息。

📞 聯繫方式

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