internetkid2001/totalcontrol

System Control & Automation MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI agents with powerful system control capabilities including keyboard automation, window management, screen capture, system monitoring, and universal application launching for Linux, macOS, and Windows.

🚀 Features

⌨️ Keyboard Control

• Type text with configurable speed and intervals
• Press individual keys (Enter, Tab, Escape, etc.)
• Execute keyboard shortcuts (Ctrl+C, Cmd+V, Alt+Tab)
• Hold and release keys for complex key combinations

🖥️ Window Management

• List all open windows with details
• Focus/activate windows by title
• Move windows to specific screen coordinates
• Resize windows to exact dimensions
• Minimize/maximize/restore window states
• Cross-platform window control (Linux, macOS, Windows)

📸 Screen Capture

• Take full screen screenshots
• Capture specific regions of the screen
• Save screenshots to files with custom names
• Return screenshots as base64 for processing
• Image recognition capabilities

📊 System Monitoring

• CPU usage statistics (overall and per-core)
• Memory usage information (RAM and swap)
• Disk space details
• Running processes sorted by CPU/memory usage
• Network statistics (bytes sent/received, packets, errors)
• Complete system information (OS, hardware, uptime)

🚀 Universal Application Launcher ⭐ NEW!

• Launch ANY installed application on your system
• Smart application discovery across multiple package managers
• Support for Flatpak, Snap, desktop files, and PATH executables
• List all available applications with filtering by type
• Intelligent launch methods with automatic fallback
• Security safeguards against dangerous commands

🔧 File & URL Operations

• Open files with default applications
• Open URLs in default browser
• Execute safe shell commands with security restrictions

🛡️ Security Features

• Dangerous command blocking - Prevents system-damaging operations
• Timeout protection - All operations have reasonable timeouts
• Error handling - Graceful failures with helpful error messages
• PyAutoGUI failsafe - Built-in safety mechanisms

📦 Installation

Prerequisites

• Python 3.8 or higher
• pip package manager
• Claude Desktop or other MCP-compatible client

System Dependencies

Linux (Ubuntu/Debian):

sudo apt install python3-tk scrot wmctrl xdotool

Linux (Fedora):

sudo dnf install python3-tkinter scrot wmctrl xdotool

macOS:

• Grant accessibility permissions to your terminal
• No additional packages needed

Windows:

• No additional packages needed

Quick Setup

1. Clone or download this repository

2. Set up the virtual environment:

   cd totalcontrol
   python3 -m venv system_control_env
   source system_control_env/bin/activate  # Linux/macOS
   # or
   system_control_env\Scripts\activate  # Windows
   

3. Install Python dependencies:

   pip install --upgrade pip
   pip install mcp pyautogui pygetwindow psutil pillow
   
   # Linux additional dependencies
   pip install python-xlib ewmh
   
   # macOS additional dependencies
   pip install pyobjc-framework-Quartz pyobjc-framework-AppKit
   
   # Windows additional dependencies
   pip install pywin32
   

4. Test the server:

   python test_server.py
   

🔧 Configuration

Claude Desktop Integration

Add this configuration to your Claude Desktop config file:

Linux: ~/.config/claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "system-control": {
      "command": "/path/to/totalcontrol/system_control_env/bin/python",
      "args": ["/path/to/totalcontrol/system_control_mcp.py"],
      "env": {
        "DISPLAY": ":0"
      }
    }
  }
}

🎮 Usage Examples

Application Launching

"Launch Firefox"
"Open Steam"
"Launch RPCS3"
"Open Visual Studio Code"
"Launch any application name"

Application Discovery

"List all applications"
"Show me Flatpak applications"
"List desktop applications"
"What applications can I launch?"

Screen Capture

"Take a screenshot"
"Save a screenshot as desktop.png"
"Capture the screen"

System Monitoring

"What's my CPU usage?"
"Show me system information"
"List running processes"
"What's my memory usage?"

Keyboard Automation

"Type 'Hello World'"
"Press Enter 3 times"
"Execute Ctrl+C"
"Hold Shift and press the right arrow"

Window Management

"List all open windows"
"Focus the Firefox window"
"Minimize all windows"
"Resize the terminal to 800x600"

🔧 Available Tools

🧪 Testing

# Test server functionality
python test_server.py

# Test individual tools
python test_tools.py

# Test server startup
python system_control_mcp.py

🔍 Application Discovery

The server automatically discovers applications from:

• 📦 Flatpak applications - All installed Flatpak apps
• 📱 Snap packages - All installed Snap applications
• 🖥️ Desktop files - Applications with .desktop entries
• ⚡ PATH executables - Command-line tools and applications

Total applications discovered: 2700+ on a typical Linux system!

🛡️ Security

Blocked Operations

The server blocks dangerous commands including:

• File operations: rm, mv, cp, dd
• System control: shutdown, reboot, sudo, su
• Network tools: wget, curl, ssh, nc
• Shell access: bash, sh, exec, eval

Safe Operations

Allows safe applications and commands:

• All GUI applications (games, media players, etc.)
• Development tools (IDEs, editors, etc.)
• System utilities (file managers, terminals, etc.)
• Media applications (browsers, video players, etc.)

🔧 Troubleshooting

Common Issues

1. "No DISPLAY variable" (Linux)

• You're running in a headless environment
• Need X11 forwarding or a graphical desktop

2. "Permission denied" errors

• Grant accessibility permissions (macOS)
• Run as administrator if needed (Windows)
• Check user permissions (Linux)

3. "Module not found" errors

• Activate the virtual environment first
• Install missing dependencies

4. Applications won't launch

• Check if the application is installed
• Use list_applications to see available apps
• Try the exact name from the application list

Platform-Specific Notes

Linux:

• Requires X11 display server
• Some window management needs wmctrl and xdotool
• Screenshot functionality needs scrot

macOS:

• Requires accessibility permissions for automation
• Uses native macOS APIs for window management

Windows:

• May require administrator privileges for some operations
• Uses native Windows APIs

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📝 License

This project is open source. See the LICENSE file for details.

🔗 Related Projects

• Model Context Protocol - The protocol this server implements
• Claude Desktop - The primary client for this server
• PyAutoGUI - GUI automation library used

📊 Version History

• v1.0.0 - Initial release with basic functionality
• v1.1.0 - Added universal application launching ⭐
• v1.1.1 - Enhanced application discovery and security

⚠️ Important Security Notice: This server can control your computer. Only use it with trusted AI assistants and review actions before execution. The server includes security safeguards but should be used responsibly.