Skip to content
Back to search

winremote-mcp

Windows Remote MCP Server — 40+ tools for desktop automation, process management, file operations via FastMCP

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/dddabtc--winremote-mcp/badge.svg)](/listings/dddabtc--winremote-mcp)

HTML

<a href="/listings/dddabtc--winremote-mcp"><img src="/api/listings/dddabtc--winremote-mcp/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.

# Install from PyPI
pip install winremote-mcp

# Start the Windows MCP server
winremote-mcp

That's it! Your Windows MCP server is now running on `http://127.0.0.1:8090` and ready to accept commands from MCP clients like Claude Desktop.

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 · 669 lines

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

  1. # WinRemote MCP — Run MCP Servers Remotely on Windows
  2. [中文说明](README.zh-CN.md) | [English README](README.md)
  3. [![PyPI version](https://img.shields.io/pypi/v/winremote-mcp)](https://pypi.org/project/winremote-mcp/)
  4. [![Python](https://img.shields.io/pypi/pyversions/winremote-mcp)](https://pypi.org/project/winremote-mcp/)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. [![CI](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml)
  7. [![Downloads](https://static.pepy.tech/badge/winremote-mcp)](https://pepy.tech/projects/winremote-mcp)
  8. [![win-remote-mcp MCP server](https://glama.ai/mcp/servers/dddabtc/win-remote-mcp/badges/score.svg)](https://glama.ai/mcp/servers/dddabtc/win-remote-mcp)
  9. **The ultimate Windows MCP server for remote desktop control and automation.** Control any Windows machine through the Model Context Protocol — perfect for AI agents, Claude Desktop. Transform your Windows desktop into a powerful, remotely-accessible automation endpoint.
  10. Run **on the Windows machine** you want to control. Built with [FastMCP](https://github.com/jlowin/fastmcp) and the [Model Context Protocol](https://modelcontextprotocol.io/).
  11. ## Quickstart (30 seconds)
  12. ```bash
  13. # Install from PyPI
  14. pip install winremote-mcp
  15. # Start the Windows MCP server
  16. winremote-mcp
  17. ```
  18. That's it! Your Windows MCP server is now running on `http://127.0.0.1:8090` and ready to accept commands from MCP clients like Claude Desktop.
  19. ## 🤖 Agent Integrations
  20. winremote-mcp works with MCP-compatible AI agents and clients. Client-specific setup guides live in this repo:
  21. - [Hermes](skill/hermes/) — add winremote as a native streamable HTTP or stdio MCP server.
  22. - [OpenClaw](skill/openclaw/) — use winremote as OpenClaw's Windows control layer.
  23. - [Claude Desktop / Claude Code](skill/claude/) — configure local stdio or remote streamable HTTP.
  24. - [Cursor](skill/cursor/) — add winremote to `.cursor/mcp.json`.
  25. ### Hermes Setup
  26. Run winremote-mcp on the Windows machine, then add it to Hermes as an MCP server:
  27. ```powershell
  28. pip install winremote-mcp
  29. winremote-mcp --host 0.0.0.0 --port 8090 --auth-key "your-secret-key"
  30. ```
  31. ```yaml
  32. mcp_servers:
  33. winremote:
  34. type: streamable-http
  35. url: http://<windows-ip>:8090/mcp
  36. headers:
  37. Authorization: Bearer your-secret-key
  38. ```
  39. See the full [Hermes integration guide](skill/hermes/) for local stdio setup, verification prompts, and available capabilities.
  40. ## 🤖 OpenClaw Integration
  41. winremote-mcp is the official Windows control layer for [OpenClaw](https://github.com/openclaw/openclaw). Together they give your AI agent full remote control over any Windows machine — screenshots, PowerShell, file transfer, GUI automation, and more.
  42. ---
  43. ### The Easiest Way: Just Tell OpenClaw
  44. You don't need to configure anything manually. Just tell your OpenClaw agent:
  45. > "Install winremote-mcp on my Windows machine at `192.168.1.100` and connect it to yourself. Python is installed at `C:\Python311\python.exe`."
  46. OpenClaw will SSH into the Windows machine, install the package, start the server, and wire up the MCP connection — all automatically.
  47. ---
  48. ### Manual Setup (Step by Step)
  49. #### Step 1 — Install on Windows
  50. ```cmd
  51. pip install winremote-mcp
  52. ```
  53. #### Step 2 — Start the server
  54. **Local-only quick start (default, safest):**
  55. ```cmd
  56. winremote-mcp
  57. ```
  58. **Remote access requires authentication:**
  59. Starting with v0.4.20, `winremote-mcp` refuses to bind HTTP transport to a non-loopback address without authentication. Use an API key for LAN or remote access:
  60. ```cmd
  61. winremote-mcp --host 0.0.0.0 --port 8090 --auth-key YOUR_SECRET_KEY
  62. ```
  63. For lab-only legacy behavior, you can explicitly acknowledge the risk with `--allow-insecure-remote`; do not use this on shared, routed, or internet-exposed networks.
  64. **Auto-start on boot:**
  65. ```cmd
  66. winremote-mcp install
  67. ```
  68. #### Step 3 — Connect OpenClaw
  69. Add to your `openclaw.json`:
  70. ```json
  71. {
  72. "plugins": {
  73. "entries": {
  74. "winremote": {
  75. "type": "mcp",
  76. "url": "http://192.168.1.100:8090/mcp",
  77. "headers": {
  78. "Authorization": "Bearer YOUR_SECRET_KEY"
  79. }
  80. }
  81. }
  82. }
  83. }
  84. ```
  85. Or tell your OpenClaw agent:
  86. > "Add winremote MCP at `http://192.168.1.100:8090/mcp` with auth key `YOUR_SECRET_KEY`."
  87. #### Step 4 — What your agent can do
  88. Once connected, your AI agent has full Windows control:
  89. | Capability | Example |
  90. |------------|---------|
  91. | 🖥️ Screenshots | Capture the full desktop or a specific window |
  92. | ⚡ Shell execution | Run PowerShell, CMD, or batch scripts |
  93. | 📁 File transfer | Upload/download files between Linux and Windows |
  94. | 🖱️ GUI automation | Click, type, drag — control any Windows app |
  95. | 🔧 System info | Process list, services, event logs, registry |
  96. | 📷 OCR | Extract text from any screen region |
  97. | 🎬 Screen recording | Record desktop activity as GIF |
  98. ---
  99. ### Secure Remote Access (HTTPS)
  100. For access over the internet or untrusted networks, enable HTTPS:
  101. **Step 1 — Generate a certificate:**
  102. ```bash
  103. # Self-signed (LAN/homelab)
  104. openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
  105. # Trusted cert (no browser warnings) — requires mkcert installed
  106. mkcert -install && mkcert 192.168.1.100
  107. ```
  108. **Step 2 — Start with TLS:**
  109. ```cmd
  110. winremote-mcp --host 0.0.0.0 --port 8090 ^
  111. --auth-key YOUR_SECRET_KEY ^
  112. --ssl-certfile cert.pem ^
  113. --ssl-keyfile key.pem
  114. ```
  115. **OpenClaw config with HTTPS:**
  116. ```json
  117. {
  118. "plugins": {
  119. "entries": {
  120. "winremote": {
  121. "type": "mcp",
  122. "url": "https://192.168.1.100:8090/mcp",
  123. "headers": {
  124. "Authorization": "Bearer YOUR_SECRET_KEY"
  125. }
  126. }
  127. }
  128. }
  129. }
  130. ```
  131. ---
  132. ### OAuth 2.0 (for Claude Desktop and other MCP clients)
  133. Some MCP clients (like Claude Desktop) use OAuth instead of API keys. OAuth is a pre-provisioned confidential-client flow: configure both client ID and client secret on the server, then copy the same values into the client. Dynamic client registration is disabled, and redirect URIs must be loopback `http(s)` URIs.
  134. ```cmd
  135. winremote-mcp --host 0.0.0.0 --port 8090 ^
  136. --ssl-certfile cert.pem --ssl-keyfile key.pem ^
  137. --oauth-client-id my-client --oauth-client-secret my-secret
  138. ```
  139. **Claude Desktop config (`claude_desktop_config.json`):**
  140. ```json
  141. {
  142. "mcpServers": {
  143. "winremote": {
  144. "type": "http",
  145. "url": "https://192.168.1.100:8090/mcp/",
  146. "oauth": {
  147. "clientId": "my-client",
  148. "clientSecret": "my-secret"
  149. }
  150. }
  151. }
  152. }
  153. ```
  154. ---
  155. ### `winremote.toml` — Full Config Reference
  156. Place in your working directory or `~/.config/winremote/winremote.toml`:
  157. ```toml
  158. [server]
  159. host = "0.0.0.0"
  160. port = 8090
  161. auth_key = "your-secret-key"
  162. # Optional break-glass flag for legacy trusted-LAN deployments only.
  163. # Remote HTTP without auth is refused unless this is true.
  164. allow_insecure_remote = false
  165. ssl_certfile = "C:/certs/cert.pem" # optional — enables HTTPS
  166. ssl_keyfile = "C:/certs/key.pem" # optional — enables HTTPS
  167. [security]
  168. ip_allowlist = ["192.168.1.0/24"] # restrict to LAN only
  169. oauth_client_id = "" # optional OAuth client ID
  170. oauth_client_secret = "" # optional OAuth secret
  171. [tools]
  172. exclude = ["ScreenRecord"] # disable specific tools
  173. ```
  174. ---
  175. > **Note:** winremote-mcp is a standard MCP server and works with any MCP-compatible client — Claude Desktop, Cursor, OpenClaw, and others.
  176. ## Tool error semantics
  177. Tool execution failures are returned through the MCP protocol with `isError: true`. The error text still includes the tool name and the underlying diagnostic so clients can display a useful message, while retries, fallbacks, and task status handling can reliably distinguish failures from successful text results.
  178. **Compatibility:** clients must handle MCP tool errors instead of treating strings such as `"ServiceList error: ..."` as successful output. Code that previously pattern-matched those strings should switch to the client's standard MCP error path. Successful tool result formats are unchanged.
  179. ## What's New in v0.4.24
  180. ### 🐛 Reliable MCP tool errors
  181. - Tool execution failures now set `isError: true` through FastMCP's standard `ToolError` path instead of appearing as successful string results.
  182. - Service, network, registry, and OCR helper exceptions retain useful diagnostics at the MCP boundary.
  183. - Task tracking still records failed status and diagnostics before propagating the error to the client.
  184. ### 🔒 Dependency security updates
  185. - Raised minimum versions for newly disclosed vulnerabilities in AnyIO, cryptography, HTTPX 2, PyJWT, and Soup Sieve.
  186. ## What's New in v0.4.23
  187. ### 🐛 FastMCP debug/uvicorn compatibility
  188. - Fixed `winremote-mcp --debug` with FastMCP 3.2.4+, where `run_http_async` renamed the uvicorn options keyword from `uvicorn_args` to `uvicorn_config`.
  189. - winremote-mcp now detects the installed FastMCP signature and passes DEBUG uvicorn logging through the supported keyword, while preserving compatibility with older FastMCP releases.
  190. - Added regression coverage so the debug HTTP startup path stays compatible with both keyword names.
  191. Chinese release notes are available in [README.zh-CN.md](README.zh-CN.md).
  192. For older release notes, see the full [CHANGELOG](CHANGELOG.md).
  193. ## What Problem It Solves
  194. - **Remote Windows Control**: Control Windows desktops from anywhere through standardized MCP protocol
  195. - **AI Agent Integration**: Enable Claude, GPT, and other AI agents to interact with Windows GUI applications
  196. - **Cross-Platform Automation**: Bridge the gap between Linux/macOS development environments and Windows targets
  197. - **Headless Windows Management**: Manage Windows servers and workstations without RDP or VNC overhead
  198. ## Features
  199. - **Desktop Control** — Screenshot capture (JPEG compressed, multi-monitor), click, type, scroll, keyboard shortcuts
  200. - **Window Management** — Focus windows, minimize-all, launch/resize applications, multi-monitor support
  201. - **Remote Shell Access** — PowerShell command execution with working directory support
  202. - **File Operations** — Read, write, list, search files; binary transfer via base64 encoding
  203. - **System Administration** — Windows Registry access, service management, scheduled tasks, process control
  204. - **Network Tools** — Ping hosts, check TCP ports, monitor network connections
  205. - **Advanced Features** — OCR text extraction, screen recording (GIF), annotated screenshots with UI element labels
  206. - **AI Vision Support** — Works with Flutter, Electron, Qt and any UI via AI vision. See [Vision Guide](docs/vision-guide.md)
  207. - **Security & Auth** — Optional API key authentication, localhost-only binding by default
  208. ## Installation
  209. ### From PyPI (Recommended)
  210. ```bash
  211. pip install winremote-mcp
  212. ```
  213. ### From Source
  214. ```bash
  215. git clone https://github.com/dddabtc/winremote-mcp.git
  216. cd winremote-mcp
  217. pip install .
  218. ```
  219. ### With Optional Dependencies
  220. ```bash
  221. # Install with OCR support (includes pytesseract)
  222. pip install winremote-mcp[ocr]
  223. # Install development dependencies
  224. pip install winremote-mcp[test]
  225. ```
  226. ### OCR Setup (Optional)
  227. For text extraction from screenshots:
  228. ```bash
  229. # 1. Install Tesseract OCR engine
  230. winget install UB-Mannheim.TesseractOCR
  231. # 2. Install with OCR dependencies
  232. pip install winremote-mcp[ocr]
  233. ```
  234. ## Usage
  235. ### Basic Usage
  236. ### Tier and tool controls
  237. ```bash
  238. # Default: tier1 + tier2 enabled, tier3 disabled
  239. winremote-mcp
  240. # Enable destructive tier3 tools
  241. winremote-mcp --enable-tier3
  242. # Disable interactive tier2 (tier1 only)
  243. winremote-mcp --disable-tier2
  244. # Both together: tier1 + tier3 (tier2 disabled)
  245. winremote-mcp --enable-tier3 --disable-tier2
  246. # Backward-compatible: enable everything
  247. winremote-mcp --enable-all
  248. # Explicit tool list (highest precedence over tier flags)
  249. winremote-mcp --tools Snapshot,Click,Type
  250. # Remove specific tools from resolved set
  251. winremote-mcp --enable-tier3 --exclude-tools Shell,FileWrite
  252. ```
  253. ### Config file (`winremote.toml`)
  254. Search order:
  255. 1. `--config /path/to/winremote.toml`
  256. 2. `./winremote.toml`
  257. 3. `~/.config/winremote/winremote.toml`
  258. ```toml
  259. [server]
  260. host = "127.0.0.1"
  261. port = 8090
  262. auth_key = ""
  263. ssl_certfile = "" # Path to SSL certificate for HTTPS
  264. ssl_keyfile = "" # Path to SSL private key for HTTPS
  265. [security]
  266. ip_allowlist = ["127.0.0.1", "192.168.1.0/24"]
  267. enable_tier3 = false
  268. disable_tier2 = false
  269. oauth_client_id = "" # Expected OAuth client ID (optional)
  270. oauth_client_secret = "" # OAuth client secret for confidential clients
  271. [tools]
  272. enable = ["Snapshot", "Click", "Type"]
  273. exclude = []
  274. ```
  275. **Precedence:** CLI flags override config file values; config file values override defaults.
  276. ### IP allowlist
  277. ```bash
  278. # CLI
  279. winremote-mcp --ip-allowlist 127.0.0.1,192.168.1.0/24
  280. # Or via config [security].ip_allowlist
  281. ```
  282. Supports both single IPs and CIDR ranges (IPv4/IPv6). Non-allowlisted clients receive HTTP 403 with a clear error.
  283. ### HTTPS / TLS
  284. To enable HTTPS, provide SSL certificate and key files:
  285. ```bash
  286. winremote-mcp --ssl-certfile cert.pem --ssl-keyfile key.pem
  287. ```
  288. Or in `winremote.toml`:
  289. ```toml
  290. [server]
  291. ssl_certfile = "/path/to/cert.pem"
  292. ssl_keyfile = "/path/to/key.pem"
  293. ```
  294. **Generate a self-signed certificate** (for local/LAN use):
  295. ```bash
  296. openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
  297. ```
  298. ### OAuth 2.0
  299. WinRemote MCP includes a built-in OAuth 2.0 Authorization Server, compatible with Claude Desktop and other MCP clients that require OAuth.
  300. Enable it with:
  301. ```bash
  302. winremote-mcp --oauth-client-id my-client --oauth-client-secret my-secret
  303. ```
  304. Or in `winremote.toml`:
  305. ```toml
  306. [security]
  307. oauth_client_id = "my-client"
  308. oauth_client_secret = "my-secret"
  309. ```
  310. **Claude Desktop config** (`claude_desktop_config.json`):
  311. ```json
  312. {
  313. "mcpServers": {
  314. "winremote": {
  315. "type": "http",
  316. "url": "https://your-host:8080/mcp/",
  317. "oauth": {
  318. "clientId": "my-client",
  319. "clientSecret": "my-secret"
  320. }
  321. }
  322. }
  323. }
  324. ```
  325. The OAuth server implements:
  326. - `GET /.well-known/oauth-authorization-server` — server metadata (RFC 8414)
  327. - `POST /oauth/register` — dynamic client registration (RFC 7591)
  328. - `GET /oauth/authorize` — Authorization Code + PKCE (RFC 7636)
  329. - `POST /oauth/token` — token exchange
  330. ### Health check
  331. ```bash
  332. # Start MCP server (localhost only, no auth)
  333. winremote-mcp
  334. # Start with remote access and authentication
  335. winremote-mcp --host 0.0.0.0 --port 8090 --auth-key "your-secret-key"
  336. # Enable all tools including high-risk Tier 3 (Shell, FileWrite, etc.)
  337. winremote-mcp --enable-all
  338. # Start with hot reload for development
  339. winremote-mcp --reload
  340. ```
  341. ### MCP Client Configuration
  342. **For Claude Desktop (`claude_desktop_config.json`):**
  343. ```json
  344. {
  345. "mcpServers": {
  346. "winremote": {
  347. "command": "winremote-mcp",
  348. "args": ["--transport", "stdio"]
  349. }
  350. }
  351. }
  352. ```
  353. **For HTTP MCP clients:**
  354. ```json
  355. {
  356. "mcpServers": {
  357. "winremote": {
  358. "type": "streamable-http",
  359. "url": "http://192.168.1.100:8090/mcp",
  360. "headers": {
  361. "Authorization": "Bearer your-secret-key"
  362. }
  363. }
  364. }
  365. }
  366. ```
  367. ### Auto-Start on Boot
  368. ```bash
  369. # Create Windows scheduled task
  370. winremote-mcp install
  371. # Remove scheduled task
  372. winremote-mcp uninstall
  373. ```
  374. ## Security
  375. Tools are organized into three risk tiers. By default, only Tier 1-2 tools are enabled.
  376. | Tier | Risk | Default | Examples |
  377. |------|------|---------|----------|
  378. | **Tier 1** | Read-only | ✅ Enabled | Snapshot, GetSystemInfo, FileList |
  379. | **Tier 2** | Interactive | ✅ Enabled | Click, Type, Shortcut, Scrape |
  380. | **Tier 3** | Destructive / server-side effects | ❌ Disabled | Shell, App, PlaySound, FileWrite |
  381. ```bash
  382. # Enable all tiers (use with caution)
  383. winremote-mcp --enable-all
  384. # Always use auth for remote access
  385. winremote-mcp --host 0.0.0.0 --auth-key "your-secret-key"
  386. ```
  387. See [SECURITY.md](SECURITY.md) for the full security guide.
  388. ## Tools
  389. | Tool | Description |
  390. |------|-------------|
  391. | **Desktop** | |
  392. | Snapshot | Screenshot (JPEG, configurable quality/max_width) + window list + UI elements |
  393. | AnnotatedSnapshot | Screenshot with numbered labels on interactive elements |
  394. | OCR | Extract text from screen via OCR (pytesseract or Windows built-in) |
  395. | ScreenRecord | Record screen activity as animated GIF |
  396. | PlaySound | Play audio file on Windows host (.wav/.mp3/.ogg/.wma/.m4a, local path or URL) |
  397. | **Input** | |
  398. | Click | Mouse click (left/right/middle, single/double/hover) |
  399. | Type | Type text at coordinates |
  400. | Scroll | Vertical/horizontal scroll |
  401. | Move | Move mouse / drag |
  402. | Shortcut | Keyboard shortcuts |
  403. | Wait | Pause execution |
  404. | **Window Management** | |
  405. | FocusWindow | Bring window to front (fuzzy title match) |
  406. | MinimizeAll | Show desktop (Win+D) |
  407. | App | Launch/switch/resize applications |
  408. | **System** | |
  409. | Shell | Execute PowerShell commands (with optional cwd) |
  410. | GetClipboard | Read clipboard |
  411. | SetClipboard | Write clipboard |
  412. | ListProcesses | Process list with CPU/memory |
  413. | KillProcess | Kill process by PID or name |
  414. | GetSystemInfo | System information |
  415. | Notification | Windows toast notification |
  416. | LockScreen | Lock workstation |
  417. | ReconnectSession | Reconnect disconnected Windows desktop session to console |
  418. | **File System** | |
  419. | FileRead | Read file content |
  420. | FileWrite | Write file content |
  421. | FileList | List directory contents |
  422. | FileSearch | Search files by pattern |
  423. | FileDownload | Download file as base64 (binary) |
  424. | FileUpload | Upload file from base64 (binary) |
  425. | **Registry & Services** | |
  426. | RegRead | Read Windows Registry value |
  427. | RegWrite | Write Windows Registry value |
  428. | ServiceList | List Windows services |
  429. | ServiceStart | Start a Windows service |
  430. | ServiceStop | Stop a Windows service |
  431. | **Scheduled Tasks** | |
  432. | TaskList | List scheduled tasks |
  433. | TaskCreate | Create a scheduled task |
  434. | TaskDelete | Delete a scheduled task |
  435. | **Network** | |
  436. | Scrape | Fetch URL content |
  437. | Ping | Ping a host |
  438. | PortCheck | Check if a TCP port is open |
  439. | NetConnections | List network connections |
  440. | EventLog | Read Windows Event Log entries |
  441. ## How It Works
  442. ```mermaid
  443. graph LR
  444. A["MCP Client<br/>(Claude/AI)"] -->|commands| B["WinRemote MCP<br/>Server"]
  445. B -->|API calls| C["Windows APIs<br/>(Win32/WMI/PS)"]
  446. C -->|results| B
  447. B -->|responses| A
  448. ```
  449. **Transport Options:**
  450. - **stdio**: Direct process communication (ideal for Claude Desktop)
  451. - **HTTP**: RESTful API with optional authentication (ideal for remote access)
  452. **Core Architecture:**
  453. 1. **Tool Layer**: 40+ Windows automation tools (screenshot, click, type, etc.)
  454. 2. **Task Manager**: Concurrency control and task cancellation
  455. 3. **Transport Layer**: MCP protocol over stdio or HTTP
  456. 4. **Security Layer**: Optional Bearer token authentication
  457. ## Working with Non-Standard UI Frameworks
  458. `AnnotatedSnapshot` uses Win32 API to detect UI elements, which doesn't work with **Flutter, Electron, Qt**, or custom-drawn UIs. Three solutions:
  459. | Approach | Setup | GPU | Best For |
  460. |----------|-------|-----|----------|
  461. | **Snapshot + Claude Vision** | None | No | Most users — Claude sees the screenshot and clicks |
  462. | **[UI-TARS Desktop](https://github.com/bytedance/UI-TARS-desktop)** | Medium | 16 GB | Highest accuracy (94.2%), best Chinese UI support |
  463. | **[OmniMCP](https://github.com/OpenAdaptAI/OmniMCP)** | Medium | 16 GB | Multi-LLM setups (LLM-agnostic) |
  464. **Quick example** — no extra tools needed:
  465. ```
  466. You: "Take a screenshot with Snapshot, find the Connect button, and click it."
  467. Claude: 1. Calls Snapshot() → sees the Flutter app screenshot
  468. 2. Vision identifies "Connect" button at (520, 340)
  469. 3. Calls Click(x=520, y=340)
  470. ```
  471. For the complete guide with setup instructions, architecture diagrams, and comparison benchmarks, see **[docs/vision-guide.md](docs/vision-guide.md)**.
  472. ## Troubleshooting / FAQ
  473. ### Q: MCP server not starting?
  474. **A:** Check Python version (requires 3.10+) and ensure no other service is using port 8090:
  475. ```bash
  476. python --version
  477. netstat -an | findstr :8090
  478. ```
  479. ### Q: Can't connect from remote machine?
  480. **A:** Use `--host 0.0.0.0` to bind to all interfaces (default is localhost only):
  481. ```bash
  482. winremote-mcp --host 0.0.0.0 --auth-key "secure-key"
  483. ```
  484. ### Q: Screenshot tool returns empty/black images?
  485. **A:** Windows may be locked or display turned off. Ensure:
  486. - Windows is unlocked and display is active
  487. - No screen saver is running
  488. - For multi-monitor setups, specify `monitor` parameter
  489. ### Q: OCR not working?
  490. **A:** Install Tesseract OCR engine:
  491. ```bash
  492. winget install UB-Mannheim.TesseractOCR
  493. pip install winremote-mcp[ocr]
  494. ```
  495. ### Q: Permission errors with registry/services?
  496. **A:** Run with administrator privileges:
  497. ```bash
  498. # Right-click Command Prompt → "Run as administrator"
  499. winremote-mcp
  500. ```
  501. ## Contributing
  502. We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
  503. ### Development Setup
  504. ```bash
  505. git clone https://github.com/dddabtc/winremote-mcp.git
  506. cd winremote-mcp
  507. pip install -e ".[test]"
  508. pytest # Run tests
  509. ```
  510. ## Acknowledgments
  511. Inspired by [Windows-MCP](https://github.com/CursorTouch/Windows-MCP) by CursorTouch. Thanks for the pioneering work on Windows desktop automation via MCP.
  512. ## License
  513. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  514. ---
  515. **Ready to automate Windows with AI?** ⚡ Install `winremote-mcp` and connect your favorite AI agent to any Windows machine in under 30 seconds.

Ratings and comments

Sign in to rate this skill.

Sign in

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