MCP CMD — Chạy lệnh Windows không bao giờ bị treo 🚀

MCP Server nhẹ, giúp AI assistant (Antigravity, Claude, Gemini CLI...) chạy lệnh CMD & PowerShell trên Windows an toàn, không bao giờ bị treo, với bảo mật đa tầng.

🔗 Repo: github.com/quangminh1212/MCP_CMD

Vấn đề gì được giải quyết?

Khi dùng AI coding assistant trên Windows, lệnh shell thường bị treo vĩnh viễn do:

• Prompt chờ nhập liệu (y/n, password...)
• Process zombie không tự tắt
• Escape ký tự đặc biệt trong PowerShell

MCP CMD xử lý tất cả bằng cách:

• ✅ Đóng stdin ngay lập tức — không prompt nào block được
• ✅ Tự kill cả process tree khi timeout — không zombie
• ✅ PowerShell chạy qua Base64 — hết lỗi escape
• ✅ Output giới hạn 10MB — không tràn bộ nhớ
• ✅ Phát hiện shell injection & lệnh nguy hiểm — cảnh báo bảo mật
• ✅ Chống path traversal & UNC injection — bảo vệ thư mục làm việc

7 Tools có sẵn

| Tool | Mô tả | |------|--------| | cmd_run | Chạy 1 lệnh CMD đơn lẻ | | cmd_batch | Chạy nhiều lệnh tuần tự (dừng khi lỗi hoặc tiếp tục) | | powershell_run | Chạy PowerShell an toàn, không lỗi escape | | system_info | Xem thông tin hệ thống (OS, RAM, user) | | process_list | Liệt kê các process đang chạy | | process_cleanup | Dọn dẹp process treo/zombie | | show_security_rules | Hiển thị cấu hình bảo mật & giới hạn runtime |

Cài đặt nhanh (3 bước)

1. Clone & cài đặt

git clone https://github.com/quangminh1212/MCP_CMD.git
cd MCP_CMD
npm install

2. Thêm vào MCP config

Thêm đoạn sau vào file cấu hình MCP của bạn (ví dụ: .gemini/settings.json, claude_desktop_config.json):

{
  "mcpServers": {
    "cmd": {
      "command": "node",
      "args": ["C:\\path\\to\\MCP_CMD\\index.js"],
      "autoApprove": ["cmd_run", "cmd_batch", "powershell_run", "system_info", "process_list", "process_cleanup", "show_security_rules"]
    }
  }
}

⚠️ Thay C:\\path\\to\\MCP_CMD bằng đường dẫn thực tế trên máy bạn.

3. Xong! 🎉

AI assistant của bạn giờ có thể chạy lệnh Windows mà không bao giờ bị treo.

Ví dụ sử dụng

Chạy lệnh CMD đơn giản

{
  "name": "cmd_run",
  "arguments": {
    "command": "echo Hello && dir /b",
    "cwd": "C:\\Projects",
    "timeout": 30000
  }
}

Chạy nhiều lệnh liên tiếp

{
  "name": "cmd_batch",
  "arguments": {
    "commands": [
      { "command": "npm install", "cwd": "C:\\Projects\\my-app" },
      { "command": "npm run build", "cwd": "C:\\Projects\\my-app" },
      { "command": "npm test", "cwd": "C:\\Projects\\my-app" }
    ],
    "timeout": 60000,
    "continueOnError": false
  }
}

Chạy PowerShell

{
  "name": "powershell_run",
  "arguments": {
    "command": "Get-Process | Sort-Object CPU -Descending | Select-Object -First 5 Name, CPU",
    "timeout": 15000
  }
}

Dọn dẹp process treo

{
  "name": "process_cleanup",
  "arguments": {
    "maxAgeSeconds": 10,
    "dryRun": false,
    "includeNode": false
  }
}

Kiến trúc Anti-Hang

┌─────────────────────────────────────────────┐
│  MCP Client (AI Assistant)                  │
│  Gửi JSON-RPC request qua stdio            │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│  MCP CMD Server (Node.js)                   │
│                                             │
│  1. spawn("cmd.exe", ["/c", command])       │
│  2. child.stdin.end()  ← đóng ngay         │
│  3. Thu stdout/stderr (giới hạn 5MB)        │
│  4. setTimeout → taskkill /T /F /PID        │
│  5. Trả kết quả khi xong hoặc timeout      │
└─────────────────────────────────────────────┘

| Bảo vệ | Cách thực hiện | |---------|---------------| | Không treo khi chờ input | stdin.end() ngay sau spawn | | Không process zombie | taskkill /T /F /PID kill cả cây process | | Không tràn bộ nhớ | Output giới hạn 10MB | | Không popup GUI | windowsHide: true | | Không lỗi escape PS | PowerShell dùng -EncodedCommand (Base64 UTF-16LE) | | Chống path traversal | resolve(normalize(cwd)) + chặn .., UNC, null byte | | Phát hiện lệnh nguy hiểm | Cảnh báo [SECURITY] cho del, format, shutdown... | | Phát hiện shell injection | Cảnh báo khi dùng &&, \|, >, ;... | | Giới hạn độ dài lệnh | Chặn lệnh > 8192 bytes |

Yêu cầu

• Node.js v18+
• Windows OS

Testing

npm test

The integration suite covers:

• MCP stdio transport through node index.js
• Wrapper startup through wrapper.js
• Launcher startup through launcher.exe
• Prompt/timeout anti-hang regression cases
• Parallel execution queue behavior
• Plain-text PowerShell error output

License

MIT © 2026 quangminh1212