MCP Terminal

🚀 MCP 終端服務器

MCP 終端服務器是一個安全的終端執行服務器，它實現了模型上下文協議（MCP）。該服務器提供受控命令執行功能，具備安全功能和資源限制，能有效保障命令執行的安全性和穩定性。

🚀 快速開始

本地設置

# 克隆倉庫
git clone https://github.com/RinardNick/mcp-terminal.git
cd mcp-terminal

# 創建並激活虛擬環境使用uv
uv venv
source .venv/bin/activate  # 或 .venv\Scripts\activate 在 Windows 上

# 安裝開發依賴項
uv pip install -e ".[dev]"

發佈到 PyPI

# 構建包
uv pip install build
python -m build

# 上傳到 PyPI
uv pip install twine
python -m twine upload dist/*

使用 MCP Inspector 測試

MCP Inspector 工具可用於測試服務器實現：

# 安裝 inspector
npm install -g @modelcontextprotocol/inspector

# 測試服務器
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"

運行測試

# 運行所有測試
pytest tests/

# 運行特定的測試文件
pytest tests/test_terminal.py

# 帶覆蓋率運行
pytest --cov=mcp_terminal tests/

使用 Claude Desktop

一旦包發佈到 PyPI：

1. 安裝 UV（如果尚未安裝）：

   pip install uv
   

2. 使用 UV 安裝包：

   uv pip install mcp-terminal
   

3. 配置 Claude Desktop： 編輯您的 Claude Desktop 配置文件（通常位於 ~/Library/Application Support/Claude/claude_desktop_config.json 在 macOS 上）：

   {
     "mcpServers": {
       "terminal": {
         "command": "uv",
         "args": [
           "pip",
           "運行",
           "mcp-terminal",
           "--allowed-commands",
           "python,pip,git,ls,cd",
           "--timeout-ms",
           "30000",
           "--max-output-size",
           "1048576"
         ]
       }
     }
   }
   

✨ 主要特性

• 命令執行：執行 shell 命令並捕獲輸出和錯誤處理。
• 安全控制：限制允許的命令並防止命令注入。
• 資源控制：
  • 命令超時。
  • 最大輸出大小限制。
• MCP 協議支持：
  • 標準 MCP 消息格式。
  • 功能廣告。
  • 流式輸出支持。

📚 詳細文檔

協議實現

服務器實現了模型上下文協議（MCP），帶有以下功能：

功能廣告

{
  "protocol": "1.0.0",
  "functions": {
    "terminal": {
      "type": "terminal",
      "version": "1.0"
    }
  }
}

消息格式

所有消息都遵循以下結構：

{
  "id": string,
  "command": string,
  "args": array,
  "result": any,
  "error": string | null
}

安全考慮

• 總是設置 allowed-commands 在生產環境中。
• 使用保守的超時和大小限制。
• 監控命令執行日誌。

貢獻

1. 叉倉庫。
2. 創建功能分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m '添加一些很棒的功能')。
4. 推送到分支 (git push origin feature/amazing-feature)。
5. 打開拉取請求。

📄 許可證

此項目根據 MIT 許可證授權，詳細信息請參閱 LICENSE 文件。