Mypc MCP

🚀 MYPC-MCP

MYPC-MCP is a powerful Model Context Protocol (MCP) server that empowers AI agents with comprehensive control over a local Windows PC. It acts as an AI assistant butler, endowing AI with vision (screenshots), hearing (system status), hands (control), and voice (automation) capabilities.

🚀 Quick Start

One-Line Installation (Windows)

# Double-click to run - automatically checks and installs everything
start.bat

Or manually:

# Install
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

# Start
python main.py

The server will start on http://localhost:9999 by default.

✨ Features

• 🖥️ Screen Tools: Capture the full screen, active window, and webcam, and perform AI analysis.
• 🪟 Window Management: List, focus, minimize, maximize, and close windows.
• 📁 File Operations: Read, write, edit, copy, move, and delete files with safety zones.
• 🔍 File Search: Conduct fast searches by integrating with Everything.
• ⌨️ Keyboard & Mouse: Automate text input and hotkey operations.
• 🧠 Smart Detection: Automatically detect the file path of the active window.
• 📊 Excel Automation: Control open Excel workbooks via xlwings.
• 📝 Office Automation: Control Word and PowerPoint via pywin32.
• 🌐 SSH Remote: Execute commands on remote Linux servers.
• 📊 System Control: Manage volume, power, notifications, and hardware status.
• 📋 Clipboard: Read and write clipboard content.
• 🐧 Bash Shell: Execute Git Bash commands with blacklist protection.

📦 Installation

Basic Config (config.json)

{
    "server": {
        "enabled": true,
        "name": "MyPC-MCP",
        "port": 9999,
        "host": "0.0.0.0",
        "domain": "localhost"
    },
    "safe_zones": [
        "%USERPROFILE%\\Documents",
        "%USERPROFILE%\\Downloads",
        "%USERPROFILE%\\Desktop",
        "D:\\"
    ]
}

Network Access Modes

Local Only (default):

{
    "server": {
        "host": "127.0.0.1",
        "domain": "localhost"
    }
}

LAN Access:

{
    "server": {
        "host": "0.0.0.0",
        "domain": "192.168.1.100"
    }
}

Run setup-firewall.bat as Administrator to allow port 9999.

💻 Usage Examples

Basic Usage

Example 1: Read and Edit a File

# List files in Documents
MyPC-list_directory(path="%USERPROFILE%\\Documents")

# Read a file
MyPC-read_file(path="%USERPROFILE%\\Documents\\notes.txt")

# Edit the file
MyPC-edit_file(
    path="%USERPROFILE%\\Documents\\notes.txt",
    search_text="old text",
    replace_text="new text"
)

Example 2: Browser Automation

# Get current browser URL
MyPC-get_browser_url()

# Take a screenshot with AI analysis
MyPC-take_screenshot(display_index=1, ai_analysis=True)

# Copy URL to clipboard
MyPC-set_clipboard(text="https://example.com")

Example 3: Window Management

# List all windows
MyPC-list_windows()

# Focus Notepad
MyPC-focus_window(title="Notepad")

# Type something
type_text(text="Hello World", enter=True)

# Save and close
hotkey(keys=["ctrl", "s"])
MyPC-close_window(title="Notepad")

Example 4: File Search

# Search for Python files
MyPC-search_files(query="*.py", limit=20)

# Search in specific directory
MyPC-search_files(query="project notes ext:pdf")

Example 5: Smart File Detection

# Detect which file is currently open
MyPC-detect_active_file()
# Returns: {
#   "path": "D:\\Projects\\main.py",
#   "filename": "main.py",
#   "software": "Python",
#   "strategy": "标题路径提取"
# }

Example 6: Remote SSH Execution

# List SSH hosts
MyPC-ssh_list_hosts()

# Execute command on remote server
MyPC-ssh_execute(host="MyServer", command="docker ps")

📚 Documentation

Available Tools

Screen & Vision

• MyPC-take_screenshot - Capture full screen or specific monitor
• MyPC-screenshot_active_window - Capture active window only
• MyPC-take_webcam_photo - Capture from webcam
• MyPC-list_monitors - List all monitors

Window Management

• MyPC-get_active_window - Get active window info
• MyPC-list_windows - List all visible windows
• MyPC-focus_window - Focus a window by title/process
• MyPC-minimize_window - Minimize a window
• MyPC-maximize_window - Maximize a window
• MyPC-close_window - Close a window
• MyPC-screenshot_active_window - Screenshot active window
• MyPC-get_browser_url - Get browser URL from address bar
• MyPC-get_focused_control - Get focused UI control info

Process Management

• MyPC-list_processes - List processes by CPU/memory usage
• MyPC-kill_process - Kill process by name or PID
• MyPC-open_app - Open application

File Operations

• MyPC-list_directory - List directory contents
• MyPC-read_file - Read files (txt, docx, xlsx, pptx, pdf)
• MyPC-write_file - Write text to file (safe zones only)
• MyPC-edit_file - Search and replace in file
• MyPC-copy_file - Copy file (into safe zones only)
• MyPC-move_file - Move/rename file (safe zones only)
• MyPC-delete_file - Delete file (moves to Recycle Bin)
• MyPC-get_file_info - Get detailed file information
• MyPC-search_files - Search files using Everything

File Search & Detection

• MyPC-search_files - Fast file search via Everything
• MyPC-detect_active_file - Smart detection of active window's file

Excel Automation

• MyPC-execute_excel_code - Execute xlwings code in active Excel
• MyPC-list_excel_books - List all open Excel workbooks

Office Automation

• MyPC-execute_word_code - Execute pywin32 code in active Word
• MyPC-execute_ppt_code - Execute pywin32 code in active PowerPoint

Input Automation

• type_text - Type text (supports Chinese via clipboard)
• hotkey - Press hotkey combinations

Clipboard

• MyPC-get_clipboard - Get clipboard content
• MyPC-set_clipboard - Set clipboard content

System Control

• MyPC-get_system_status - Get CPU, memory, battery status
• MyPC-set_volume / MyPC-get_volume - Volume control
• MyPC-lock_screen - Lock workstation
• MyPC-sleep_display - Turn off display
• MyPC-hibernate - Hibernate system

Notifications

• MyPC-show_notification - Show Windows Toast notification

Hardware

• MyPC-get_hardware_status - CPU, GPU, memory, disk info

Bash Shell

• MyPC-bash - Execute Git Bash commands
• MyPC-bash_blocked - List blocked commands
• MyPC-bash_status - Check Bash installation

SSH Remote

• MyPC-ssh_list_hosts - List configured SSH hosts
• MyPC-ssh_execute - Execute remote command
• MyPC-ssh_test_connection - Test SSH connection
• MyPC-ssh_allowed_commands - List allowed commands

Utilities

• MyPC-delay - Delay execution (1-120 seconds)

🔧 Technical Details

Security

Safe Zones

File operations are categorized by permission level:

• Read Operations: Any directory
• Write Operations: Only in configured safe zones
• Copy Operations: Can copy INTO safe zones only

SSH Security

• Command whitelist mechanism
• Password and key file authentication
• Encoded connection support

Data Protection

• Recycle Bin for file deletions
• No permanent data loss by default
• Path validation and normalization

Advanced Configuration

Environment Variables

Config supports environment variable expansion:

• %USERPROFILE% - User profile directory
• %APPDATA% - Application data
• %TEMP% - Temporary folder
• ~ - Home directory

Everything Search

To enable fast file search, install Everything and configure path in config.json:

{
    "paths": {
        "everything": [
            "C:\\Program Files\\Everything\\es.exe",
            "D:\\APP\\Everything\\es.exe"
        ]
    }
}

Git Bash

Configure Git Bash path in config.json:

{
    "paths": {
        "git_bash": [
            "C:\\Program Files\\Git\\bin\\bash.exe"
        ]
    }
}

AI Analysis (VLM)

Configure Vision Language Model for screenshot analysis:

{
    "vlm": {
        "enabled": true,
        "base_url": "https://open.bigmodel.cn/api/paas/v4",
        "api_key": "your_api_key_here",
        "model": "glm-4.6v",
        "prompt": "Please identify all text in this image."
    }
}

📁 Project Structure

MYPC-MCP/
├── main.py                   # Server entry point
├── config.example.json       # Configuration template
├── config.json              # Your configuration (gitignored)
├── requirements.txt          # Python dependencies
├── start.bat               # Quick start script
├── install.bat             # Installation script
├── stop.bat                # Stop server script
├── setup-firewall.bat      # Firewall configuration
├── tools/                   # Tool modules
│   ├── screen.py            # Screen & webcam tools
│   ├── system.py            # System control tools
│   ├── files.py             # File management tools
│   ├── window.py            # Window management tools
│   ├── search.py            # File search tools
│   ├── ssh.py               # SSH remote tools
│   ├── bash.py              # Git Bash tools
│   ├── keyboard_mouse.py    # Keyboard & mouse automation
│   ├── detector.py          # Smart file detection
│   ├── detect_active_file.py # File detection implementation
│   ├── excel.py             # Excel automation (xlwings)
│   └── office.py            # Office automation (Word/PPT)
├── utils/                   # Utility modules
│   └── config.py            # Configuration loader
└── screenshots/             # Screenshot storage

🌐 Network Access

Local Access

# Start server
python main.py

# Access from same machine
http://localhost:9999

LAN Access

1. Configure firewall (run setup-firewall.bat as Administrator)
2. Edit config.json:

   {
       "server": {
           "host": "0.0.0.0",
           "domain": "YOUR_LAN_IP"
       }
   }
   

3. Access from LAN: http://YOUR_LAN_IP:9999

WAN Access

1. Configure router port forwarding (External 9999 → Your PC:9999)
2. Run setup-firewall.bat as Administrator
3. Configure domain or use public IP

See NETWORK.md for detailed guide.

🤝 Contributing

Contributions are welcome! Please feel free to submit Pull Request.

📄 License

MIT License