Skip to content
Back to search

MCPControl

MCP server for Windows OS automation

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/claude-did-this--mcpcontrol/badge.svg)](/listings/claude-did-this--mcpcontrol)

HTML

<a href="/listings/claude-did-this--mcpcontrol"><img src="/api/listings/claude-did-this--mcpcontrol/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

1. **Install Build Tools (including VC++ workload)**

   # Run as Administrator - may take a few minutes to complete
   winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

2. **Install Python** (if not already installed)

   # Install Python (required for node-gyp)
   winget install Python.Python.3.12

3. **Install Node.js**

   # Install latest LTS version
   winget install OpenJS.NodeJS

Installation

1. **Install MCPControl Package**

   npm install -g mcp-control

Configuration

MCPControl works best in a **virtual machine at 1280x720 resolution** for optimal click accuracy.

Configure your Claude client to connect to MCPControl via SSE transport:

Option 1: Direct SSE Connection

For connecting to an MCPControl server running on a VM or remote machine:

{
  "mcpServers": {
    "MCPControl": {
      "transport": "sse",
      "url": "http://192.168.1.100:3232/mcp"
    }
  }
}

Replace `192.168.1.100:3232` with your server's IP address and port.

Option 2: Local Launch with SSE

To launch MCPControl locally with SSE transport:

{
  "mcpServers": {
    "MCPControl": {
      "command": "mcp-control",
      "args": ["--sse"]
    }
  }
}

Starting the Server

First, start the MCPControl server on your VM or local machine:

mcp-control --sse

The server will display: - Available network interfaces and their IP addresses - The port number (default: 3232) - Connection status messages

VM Setup Example

1. **Start your Windows VM** with 1280x720 resolution 2. **Install MCPControl** on the VM:

   npm install -g mcp-control

3. **Run the server** with SSE transport:

   mcp-control --sse

4. **Note the VM's IP address** (e.g., `192.168.1.100`) 5. **Configure Claude** with the SSE URL:

   {
     "mcpServers": {
       "MCPControl": {
         "transport": "sse",
         "url": "http://192.168.1.100:3232/mcp"
       }
     }
   }

6. **Restart Claude** and MCPControl will appear in your MCP menu!

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 342 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCPControl
  2. <p align="center">
  3. <img src="https://github.com/user-attachments/assets/1c577e56-7b8d-49e9-aaf5-b8550cc6cfc0" alt="MCPControl Logo" width="250">
  4. </p>
  5. <p align="center">
  6. <a href="https://github.com/Cheffromspace/MCPControl/releases/tag/v0.2.0">
  7. <img src="https://img.shields.io/badge/release-v0.2.0-blue.svg" alt="Latest Release">
  8. </a>
  9. </p>
  10. Windows control server for the [Model Context Protocol](https://modelcontextprotocol.io/), providing programmatic control over system operations including mouse, keyboard, window management, and screen capture functionality.
  11. > **Note**: This project currently supports Windows only.
  12. ## 🔥 Why MCPControl?
  13. MCPControl bridges the gap between AI models and your desktop, enabling secure, programmatic control of:
  14. - 🖱️ **Mouse movements and clicks**
  15. - ⌨️ **Keyboard input and shortcuts**
  16. - 🪟 **Window management**
  17. - 📸 **Screen capture and analysis**
  18. - 📋 **Clipboard operations**
  19. ## 🔌 Quick Start
  20. ### Prerequisites
  21. 1. **Install Build Tools (including VC++ workload)**
  22. ```powershell
  23. # Run as Administrator - may take a few minutes to complete
  24. winget install Microsoft.VisualStudio.2022.BuildTools --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
  25. ```
  26. 2. **Install Python** (if not already installed)
  27. ```powershell
  28. # Install Python (required for node-gyp)
  29. winget install Python.Python.3.12
  30. ```
  31. 3. **Install Node.js**
  32. ```powershell
  33. # Install latest LTS version
  34. winget install OpenJS.NodeJS
  35. ```
  36. ### Installation
  37. 1. **Install MCPControl Package**
  38. ```powershell
  39. npm install -g mcp-control
  40. ```
  41. ### Configuration
  42. MCPControl works best in a **virtual machine at 1280x720 resolution** for optimal click accuracy.
  43. Configure your Claude client to connect to MCPControl via SSE transport:
  44. #### Option 1: Direct SSE Connection
  45. For connecting to an MCPControl server running on a VM or remote machine:
  46. ```json
  47. {
  48. "mcpServers": {
  49. "MCPControl": {
  50. "transport": "sse",
  51. "url": "http://192.168.1.100:3232/mcp"
  52. }
  53. }
  54. }
  55. ```
  56. Replace `192.168.1.100:3232` with your server's IP address and port.
  57. #### Option 2: Local Launch with SSE
  58. To launch MCPControl locally with SSE transport:
  59. ```json
  60. {
  61. "mcpServers": {
  62. "MCPControl": {
  63. "command": "mcp-control",
  64. "args": ["--sse"]
  65. }
  66. }
  67. }
  68. ```
  69. ### Starting the Server
  70. First, start the MCPControl server on your VM or local machine:
  71. ```bash
  72. mcp-control --sse
  73. ```
  74. The server will display:
  75. - Available network interfaces and their IP addresses
  76. - The port number (default: 3232)
  77. - Connection status messages
  78. ### VM Setup Example
  79. 1. **Start your Windows VM** with 1280x720 resolution
  80. 2. **Install MCPControl** on the VM:
  81. ```bash
  82. npm install -g mcp-control
  83. ```
  84. 3. **Run the server** with SSE transport:
  85. ```bash
  86. mcp-control --sse
  87. ```
  88. 4. **Note the VM's IP address** (e.g., `192.168.1.100`)
  89. 5. **Configure Claude** with the SSE URL:
  90. ```json
  91. {
  92. "mcpServers": {
  93. "MCPControl": {
  94. "transport": "sse",
  95. "url": "http://192.168.1.100:3232/mcp"
  96. }
  97. }
  98. }
  99. ```
  100. 6. **Restart Claude** and MCPControl will appear in your MCP menu!
  101. ## 🔧 CLI Options
  102. MCPControl supports several command-line flags for advanced configurations:
  103. ```bash
  104. # Run with SSE transport on default port (3232)
  105. mcp-control --sse
  106. # Run with SSE on custom port
  107. mcp-control --sse --port 3000
  108. # Run with HTTPS/TLS (required for production deployments)
  109. mcp-control --sse --https --cert /path/to/cert.pem --key /path/to/key.pem
  110. # Run with HTTPS on custom port
  111. mcp-control --sse --https --port 8443 --cert /path/to/cert.pem --key /path/to/key.pem
  112. ```
  113. ### Command Line Arguments
  114. - `--sse` - Enable SSE (Server-Sent Events) transport for network access
  115. - `--port [number]` - Specify custom port (default: 3232)
  116. - `--https` - Enable HTTPS/TLS (required for remote deployments per MCP spec)
  117. - `--cert [path]` - Path to TLS certificate file (required with --https)
  118. - `--key [path]` - Path to TLS private key file (required with --https)
  119. ### Security Note
  120. According to the MCP specification, HTTPS is **mandatory** for all HTTP-based transports in production environments. When deploying MCPControl for remote access, always use the `--https` flag with valid TLS certificates.
  121. ## 🚀 Popular Use Cases
  122. ### Assisted Automation
  123. - **Application Testing**: Delegate repetitive UI testing to Claude, allowing AI to navigate through applications and report issues
  124. - **Workflow Automation**: Have Claude operate applications on your behalf, handling repetitive tasks while you focus on creative work
  125. - **Form Filling**: Let Claude handle data entry tasks with your supervision
  126. ### AI Experimentation
  127. - **AI Gaming**: Watch Claude learn to play simple games through visual feedback
  128. - **Visual Reasoning**: Test Claude's ability to navigate visual interfaces and solve visual puzzles
  129. - **Human-AI Collaboration**: Explore new interaction paradigms where Claude can see your screen and help with complex tasks
  130. ### Development and Testing
  131. - **Cross-Application Integration**: Bridge applications that don't normally communicate
  132. - **UI Testing Framework**: Create robust testing scenarios with visual validation
  133. - **Demo Creation**: Automate the creation of product demonstrations
  134. ## ⚠️ IMPORTANT DISCLAIMER
  135. **THIS SOFTWARE IS EXPERIMENTAL AND POTENTIALLY DANGEROUS**
  136. By using this software, you acknowledge and accept that:
  137. - Giving AI models direct control over your computer through this tool is inherently risky
  138. - This software can control your mouse, keyboard, and other system functions which could potentially cause unintended consequences
  139. - You are using this software entirely at your own risk
  140. - The creators and contributors of this project accept NO responsibility for any damage, data loss, or other consequences that may arise from using this software
  141. - This tool should only be used in controlled environments with appropriate safety measures in place
  142. **USE AT YOUR OWN RISK**
  143. ## 🌟 Features
  144. <table>
  145. <tr>
  146. <td>
  147. <h3>🪟 Window Management</h3>
  148. <ul>
  149. <li>List all windows</li>
  150. <li>Get active window info</li>
  151. <li>Focus, resize & reposition</li>
  152. </ul>
  153. </td>
  154. <td>
  155. <h3>🖱️ Mouse Control</h3>
  156. <ul>
  157. <li>Precision movement</li>
  158. <li>Click & drag operations</li>
  159. <li>Scrolling & position tracking</li>
  160. </ul>
  161. </td>
  162. </tr>
  163. <tr>
  164. <td>
  165. <h3>⌨️ Keyboard Control</h3>
  166. <ul>
  167. <li>Text input & key combos</li>
  168. <li>Key press/release control</li>
  169. <li>Hold key functionality</li>
  170. </ul>
  171. </td>
  172. <td>
  173. <h3>📸 Screen Operations</h3>
  174. <ul>
  175. <li>High-quality screenshots</li>
  176. <li>Screen size detection</li>
  177. <li>Active window capture</li>
  178. </ul>
  179. </td>
  180. </tr>
  181. </table>
  182. ## 🔧 Automation Providers
  183. MCPControl supports multiple automation providers for different use cases:
  184. - **keysender** (default) - Native Windows automation with high reliability
  185. - **powershell** - Windows PowerShell-based automation for simpler operations
  186. - **autohotkey** - AutoHotkey v2 scripting for advanced automation needs
  187. ### Provider Configuration
  188. You can configure the automation provider using environment variables:
  189. ```bash
  190. # Use a specific provider for all operations
  191. export AUTOMATION_PROVIDER=autohotkey
  192. # Configure AutoHotkey executable path (if not in PATH)
  193. export AUTOHOTKEY_PATH="C:\Program Files\AutoHotkey\v2\AutoHotkey.exe"
  194. ```
  195. Or use modular configuration for specific operations:
  196. ```bash
  197. # Mix and match providers for different operations
  198. export AUTOMATION_KEYBOARD_PROVIDER=autohotkey
  199. export AUTOMATION_MOUSE_PROVIDER=keysender
  200. export AUTOMATION_SCREEN_PROVIDER=keysender
  201. export AUTOMATION_CLIPBOARD_PROVIDER=powershell
  202. ```
  203. See provider-specific documentation:
  204. - [AutoHotkey Provider](src/providers/autohotkey/README.md)
  205. ## 🛠️ Development Setup
  206. If you're interested in contributing or building from source, please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions.
  207. ### Development Requirements
  208. To build this project for development, you'll need:
  209. 1. Windows operating system (required for the keysender dependency)
  210. 2. Node.js 18 or later (install using the official Windows installer which includes build tools)
  211. 3. npm package manager
  212. 4. Native build tools:
  213. - node-gyp: `npm install -g node-gyp`
  214. - cmake-js: `npm install -g cmake-js`
  215. The keysender dependency relies on Windows-specific native modules that require these build tools.
  216. ## 📋 Project Structure
  217. - `/src`
  218. - `/handlers` - Request handlers and tool management
  219. - `/tools` - Core functionality implementations
  220. - `/types` - TypeScript type definitions
  221. - `index.ts` - Main application entry point
  222. ## 🔖 Repository Branches
  223. - **`main`** - Main development branch with the latest features and changes
  224. - **`release`** - Stable release branch that mirrors the latest stable tag (currently v0.2.0)
  225. ### Version Installation
  226. You can install specific versions of MCPControl using npm:
  227. ```bash
  228. # Install the latest stable release (from release branch)
  229. npm install mcp-control
  230. # Install a specific version
  231. npm install mcp-control@0.1.22
  232. ```
  233. ## 📚 Dependencies
  234. - [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - MCP SDK for protocol implementation
  235. - [keysender](https://www.npmjs.com/package/keysender) - Windows-only UI automation library
  236. - [clipboardy](https://www.npmjs.com/package/clipboardy) - Clipboard handling
  237. - [sharp](https://www.npmjs.com/package/sharp) - Image processing
  238. - [uuid](https://www.npmjs.com/package/uuid) - UUID generation
  239. ## 🚧 Known Limitations
  240. - Window minimize/restore operations are currently unsupported
  241. - Multiple screen functions may not work as expected, depending on setup
  242. - The get_screenshot utility does not work with the VS Code Extension Cline. See [GitHub issue #1865](https://github.com/cline/cline/issues/1865)
  243. - Some operations may require elevated permissions depending on the target application
  244. - Only Windows is supported
  245. - MCPControl works best at 1280x720 resolution, single screen. Click accuracy is optimized for this resolution. We're working on an offset/scaling bug and looking for testers or help creating testing tools
  246. ## 👥 Contributing
  247. See [CONTRIBUTING.md](CONTRIBUTING.md)
  248. ## ⚖️ License
  249. This project is licensed under the MIT License - see the LICENSE file for details.
  250. ## 📖 References
  251. - [Model Context Protocol Documentation](https://modelcontextprotocol.github.io/)
  252. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/cheffromspace-mcpcontrol-badge.png)](https://mseep.ai/app/cheffromspace-mcpcontrol)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.