{"id":44126105,"url":"https://github.com/dddabtc/winremote-mcp","last_synced_at":"2026-05-05T04:09:37.351Z","repository":{"id":337294226,"uuid":"1153027372","full_name":"dddabtc/winremote-mcp","owner":"dddabtc","description":"Windows Remote MCP Server — 40+ tools for desktop automation, process management, file operations via FastMCP","archived":false,"fork":false,"pushed_at":"2026-04-11T23:53:05.000Z","size":465,"stargazers_count":98,"open_issues_count":1,"forks_count":25,"subscribers_count":12,"default_branch":"master","last_synced_at":"2026-04-12T01:20:33.414Z","etag":null,"topics":["agent","automation","claude","mcp","model-context-protocol","openai","openclaw","python","remote","tooling","windows"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dddabtc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T19:41:22.000Z","updated_at":"2026-04-11T23:53:09.000Z","dependencies_parsed_at":"2026-03-04T17:02:59.039Z","dependency_job_id":null,"html_url":"https://github.com/dddabtc/winremote-mcp","commit_stats":null,"previous_names":["dddabtc/winremote-mcp"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/dddabtc/winremote-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dddabtc%2Fwinremote-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dddabtc%2Fwinremote-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dddabtc%2Fwinremote-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dddabtc%2Fwinremote-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dddabtc","download_url":"https://codeload.github.com/dddabtc/winremote-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dddabtc%2Fwinremote-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31779949,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","automation","claude","mcp","model-context-protocol","openai","openclaw","python","remote","tooling","windows"],"created_at":"2026-02-08T21:19:56.363Z","updated_at":"2026-05-05T04:09:37.344Z","avatar_url":"https://github.com/dddabtc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WinRemote MCP — Run MCP Servers Remotely on Windows\n\n[![PyPI version](https://img.shields.io/pypi/v/winremote-mcp)](https://pypi.org/project/winremote-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/winremote-mcp)](https://pypi.org/project/winremote-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml)\n[![Downloads](https://static.pepy.tech/badge/winremote-mcp)](https://pepy.tech/projects/winremote-mcp)\n[![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)\n\n**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.\n\nRun **on the Windows machine** you want to control. Built with [FastMCP](https://github.com/jlowin/fastmcp) and the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n## Quickstart (30 seconds)\n\n```bash\n# Install from PyPI\npip install winremote-mcp\n\n# Start the Windows MCP server\nwinremote-mcp\n```\n\nThat'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.\n\n## 🤖 Agent Integrations\n\nwinremote-mcp works with MCP-compatible AI agents and clients. Client-specific setup guides live in this repo:\n\n- [Hermes](skill/hermes/) — add winremote as a native streamable HTTP or stdio MCP server.\n- [OpenClaw](skill/openclaw/) — use winremote as OpenClaw's Windows control layer.\n- [Claude Desktop / Claude Code](skill/claude/) — configure local stdio or remote streamable HTTP.\n- [Cursor](skill/cursor/) — add winremote to `.cursor/mcp.json`.\n\n### Hermes Setup\n\nRun winremote-mcp on the Windows machine, then add it to Hermes as an MCP server:\n\n```powershell\npip install winremote-mcp\nwinremote-mcp --host 0.0.0.0 --port 8090 --auth-key \"your-secret-key\"\n```\n\n```yaml\nmcp_servers:\n  winremote:\n    type: streamable-http\n    url: http://\u003cwindows-ip\u003e:8090/mcp\n    headers:\n      Authorization: Bearer your-secret-key\n```\n\nSee the full [Hermes integration guide](skill/hermes/) for local stdio setup, verification prompts, and available capabilities.\n\n## 🤖 OpenClaw Integration\n\nwinremote-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.\n\n---\n\n### The Easiest Way: Just Tell OpenClaw\n\nYou don't need to configure anything manually. Just tell your OpenClaw agent:\n\n\u003e \"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`.\"\n\nOpenClaw will SSH into the Windows machine, install the package, start the server, and wire up the MCP connection — all automatically.\n\n---\n\n### Manual Setup (Step by Step)\n\n#### Step 1 — Install on Windows\n\n```cmd\npip install winremote-mcp\n```\n\n#### Step 2 — Start the server\n\n**Local-only quick start (default, safest):**\n```cmd\nwinremote-mcp\n```\n\n**Remote access requires authentication:**\n\nStarting 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:\n\n```cmd\nwinremote-mcp --host 0.0.0.0 --port 8090 --auth-key YOUR_SECRET_KEY\n```\n\nFor 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.\n\n**Auto-start on boot:**\n```cmd\nwinremote-mcp install\n```\n\n#### Step 3 — Connect OpenClaw\n\nAdd to your `openclaw.json`:\n\n```json\n{\n  \"plugins\": {\n    \"entries\": {\n      \"winremote\": {\n        \"type\": \"mcp\",\n        \"url\": \"http://192.168.1.100:8090/mcp\",\n        \"headers\": {\n          \"Authorization\": \"Bearer YOUR_SECRET_KEY\"\n        }\n      }\n    }\n  }\n}\n```\n\nOr tell your OpenClaw agent:\n\u003e \"Add winremote MCP at `http://192.168.1.100:8090/mcp` with auth key `YOUR_SECRET_KEY`.\"\n\n#### Step 4 — What your agent can do\n\nOnce connected, your AI agent has full Windows control:\n\n| Capability | Example |\n|------------|---------|\n| 🖥️ Screenshots | Capture the full desktop or a specific window |\n| ⚡ Shell execution | Run PowerShell, CMD, or batch scripts |\n| 📁 File transfer | Upload/download files between Linux and Windows |\n| 🖱️ GUI automation | Click, type, drag — control any Windows app |\n| 🔧 System info | Process list, services, event logs, registry |\n| 📷 OCR | Extract text from any screen region |\n| 🎬 Screen recording | Record desktop activity as GIF |\n\n---\n\n### Secure Remote Access (HTTPS)\n\nFor access over the internet or untrusted networks, enable HTTPS:\n\n**Step 1 — Generate a certificate:**\n```bash\n# Self-signed (LAN/homelab)\nopenssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes\n\n# Trusted cert (no browser warnings) — requires mkcert installed\nmkcert -install \u0026\u0026 mkcert 192.168.1.100\n```\n\n**Step 2 — Start with TLS:**\n```cmd\nwinremote-mcp --host 0.0.0.0 --port 8090 ^\n  --auth-key YOUR_SECRET_KEY ^\n  --ssl-certfile cert.pem ^\n  --ssl-keyfile key.pem\n```\n\n**OpenClaw config with HTTPS:**\n```json\n{\n  \"plugins\": {\n    \"entries\": {\n      \"winremote\": {\n        \"type\": \"mcp\",\n        \"url\": \"https://192.168.1.100:8090/mcp\",\n        \"headers\": {\n          \"Authorization\": \"Bearer YOUR_SECRET_KEY\"\n        }\n      }\n    }\n  }\n}\n```\n\n---\n\n### OAuth 2.0 (for Claude Desktop and other MCP clients)\n\nSome 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.\n\n```cmd\nwinremote-mcp --host 0.0.0.0 --port 8090 ^\n  --ssl-certfile cert.pem --ssl-keyfile key.pem ^\n  --oauth-client-id my-client --oauth-client-secret my-secret\n```\n\n**Claude Desktop config (`claude_desktop_config.json`):**\n```json\n{\n  \"mcpServers\": {\n    \"winremote\": {\n      \"type\": \"http\",\n      \"url\": \"https://192.168.1.100:8090/mcp/\",\n      \"oauth\": {\n        \"clientId\": \"my-client\",\n        \"clientSecret\": \"my-secret\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### `winremote.toml` — Full Config Reference\n\nPlace in your working directory or `~/.config/winremote/winremote.toml`:\n\n```toml\n[server]\nhost         = \"0.0.0.0\"\nport         = 8090\nauth_key     = \"your-secret-key\"\n# Optional break-glass flag for legacy trusted-LAN deployments only.\n# Remote HTTP without auth is refused unless this is true.\nallow_insecure_remote = false\nssl_certfile = \"C:/certs/cert.pem\"   # optional — enables HTTPS\nssl_keyfile  = \"C:/certs/key.pem\"    # optional — enables HTTPS\n\n[security]\nip_allowlist        = [\"192.168.1.0/24\"]   # restrict to LAN only\noauth_client_id     = \"\"                    # optional OAuth client ID\noauth_client_secret = \"\"                    # optional OAuth secret\n\n[tools]\nexclude = [\"ScreenRecord\"]   # disable specific tools\n```\n\n---\n\n\u003e **Note:** winremote-mcp is a standard MCP server and works with any MCP-compatible client — Claude Desktop, Cursor, OpenClaw, and others.\n\n## What's New in v0.4.21\n\n### 📚 README release notes cleanup\n\n- README now keeps only the latest three `What's New` sections.\n- Older release notes now point to the full [CHANGELOG](CHANGELOG.md) to keep the README focused.\n\n## What's New in v0.4.20\n\n### 🔒 Security hardening\n\n- Remote HTTP access now requires authentication by default. Non-loopback binds are refused unless you configure `--auth-key` or OAuth confidential-client auth.\n- `--allow-insecure-remote` is still available, but only as an explicit legacy / lab-only break-glass option.\n- OAuth dynamic client registration is disabled. OAuth now requires a pre-provisioned confidential client with client ID and client secret.\n- OAuth now requires PKCE `S256` and loopback redirect URIs.\n- `Scrape` and `PlaySound` URL fetching now blocks private, loopback, link-local, multicast, reserved, and unspecified targets to reduce SSRF risk.\n- `App` and `PlaySound` moved to Tier 3 because they can start programs or trigger server-side effects.\n\n### 🛡️ CI and supply-chain checks\n\n- Added CI security scans with Bandit, pip-audit, and zizmor.\n- Raised minimum dependency versions for FastMCP, Pillow, Authlib, cryptography, python-multipart, pytest, and Pygments.\n- Tightened GitHub Actions permissions and pinned workflow actions to immutable SHAs.\n\n## What's New in v0.4.19\n\n### 🤖 Hermes Integration\n\n- Added a Hermes setup guide for connecting winremote-mcp as a native MCP server.\n- Added README links to client-specific integration guides in this repository.\n\nFor older release notes, see the full [CHANGELOG](CHANGELOG.md).\n\n## What Problem It Solves\n\n- **Remote Windows Control**: Control Windows desktops from anywhere through standardized MCP protocol\n- **AI Agent Integration**: Enable Claude, GPT, and other AI agents to interact with Windows GUI applications  \n- **Cross-Platform Automation**: Bridge the gap between Linux/macOS development environments and Windows targets\n- **Headless Windows Management**: Manage Windows servers and workstations without RDP or VNC overhead\n\n## Features\n\n- **Desktop Control** — Screenshot capture (JPEG compressed, multi-monitor), click, type, scroll, keyboard shortcuts\n- **Window Management** — Focus windows, minimize-all, launch/resize applications, multi-monitor support\n- **Remote Shell Access** — PowerShell command execution with working directory support\n- **File Operations** — Read, write, list, search files; binary transfer via base64 encoding\n- **System Administration** — Windows Registry access, service management, scheduled tasks, process control\n- **Network Tools** — Ping hosts, check TCP ports, monitor network connections\n- **Advanced Features** — OCR text extraction, screen recording (GIF), annotated screenshots with UI element labels\n- **AI Vision Support** — Works with Flutter, Electron, Qt and any UI via AI vision. See [Vision Guide](docs/vision-guide.md)\n- **Security \u0026 Auth** — Optional API key authentication, localhost-only binding by default\n\n## Installation\n\n### From PyPI (Recommended)\n```bash\npip install winremote-mcp\n```\n\n### From Source\n```bash\ngit clone https://github.com/dddabtc/winremote-mcp.git\ncd winremote-mcp\npip install .\n```\n\n### With Optional Dependencies\n```bash\n# Install with OCR support (includes pytesseract)\npip install winremote-mcp[ocr]\n\n# Install development dependencies\npip install winremote-mcp[test]\n```\n\n### OCR Setup (Optional)\nFor text extraction from screenshots:\n```bash\n# 1. Install Tesseract OCR engine\nwinget install UB-Mannheim.TesseractOCR\n\n# 2. Install with OCR dependencies\npip install winremote-mcp[ocr]\n```\n\n## Usage\n\n### Basic Usage\n\n### Tier and tool controls\n```bash\n# Default: tier1 + tier2 enabled, tier3 disabled\nwinremote-mcp\n\n# Enable destructive tier3 tools\nwinremote-mcp --enable-tier3\n\n# Disable interactive tier2 (tier1 only)\nwinremote-mcp --disable-tier2\n\n# Both together: tier1 + tier3 (tier2 disabled)\nwinremote-mcp --enable-tier3 --disable-tier2\n\n# Backward-compatible: enable everything\nwinremote-mcp --enable-all\n\n# Explicit tool list (highest precedence over tier flags)\nwinremote-mcp --tools Snapshot,Click,Type\n\n# Remove specific tools from resolved set\nwinremote-mcp --enable-tier3 --exclude-tools Shell,FileWrite\n```\n\n### Config file (`winremote.toml`)\nSearch order:\n1. `--config /path/to/winremote.toml`\n2. `./winremote.toml`\n3. `~/.config/winremote/winremote.toml`\n\n```toml\n[server]\nhost = \"127.0.0.1\"\nport = 8090\nauth_key = \"\"\nssl_certfile = \"\"       # Path to SSL certificate for HTTPS\nssl_keyfile = \"\"        # Path to SSL private key for HTTPS\n\n[security]\nip_allowlist = [\"127.0.0.1\", \"192.168.1.0/24\"]\nenable_tier3 = false\ndisable_tier2 = false\noauth_client_id = \"\"    # Expected OAuth client ID (optional)\noauth_client_secret = \"\" # OAuth client secret for confidential clients\n\n[tools]\nenable = [\"Snapshot\", \"Click\", \"Type\"]\nexclude = []\n```\n\n**Precedence:** CLI flags override config file values; config file values override defaults.\n\n### IP allowlist\n```bash\n# CLI\nwinremote-mcp --ip-allowlist 127.0.0.1,192.168.1.0/24\n\n# Or via config [security].ip_allowlist\n```\n\nSupports both single IPs and CIDR ranges (IPv4/IPv6). Non-allowlisted clients receive HTTP 403 with a clear error.\n\n### HTTPS / TLS\n\nTo enable HTTPS, provide SSL certificate and key files:\n\n```bash\nwinremote-mcp --ssl-certfile cert.pem --ssl-keyfile key.pem\n```\n\nOr in `winremote.toml`:\n```toml\n[server]\nssl_certfile = \"/path/to/cert.pem\"\nssl_keyfile  = \"/path/to/key.pem\"\n```\n\n**Generate a self-signed certificate** (for local/LAN use):\n```bash\nopenssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes\n```\n\n### OAuth 2.0\n\nWinRemote MCP includes a built-in OAuth 2.0 Authorization Server, compatible with Claude Desktop and other MCP clients that require OAuth.\n\nEnable it with:\n```bash\nwinremote-mcp --oauth-client-id my-client --oauth-client-secret my-secret\n```\n\nOr in `winremote.toml`:\n```toml\n[security]\noauth_client_id     = \"my-client\"\noauth_client_secret = \"my-secret\"\n```\n\n**Claude Desktop config** (`claude_desktop_config.json`):\n```json\n{\n  \"mcpServers\": {\n    \"winremote\": {\n      \"type\": \"http\",\n      \"url\": \"https://your-host:8080/mcp/\",\n      \"oauth\": {\n        \"clientId\": \"my-client\",\n        \"clientSecret\": \"my-secret\"\n      }\n    }\n  }\n}\n```\n\nThe OAuth server implements:\n- `GET /.well-known/oauth-authorization-server` — server metadata (RFC 8414)\n- `POST /oauth/register` — dynamic client registration (RFC 7591)\n- `GET /oauth/authorize` — Authorization Code + PKCE (RFC 7636)\n- `POST /oauth/token` — token exchange\n\n### Health check\n```bash\n# Start MCP server (localhost only, no auth)\nwinremote-mcp\n\n# Start with remote access and authentication\nwinremote-mcp --host 0.0.0.0 --port 8090 --auth-key \"your-secret-key\"\n\n# Enable all tools including high-risk Tier 3 (Shell, FileWrite, etc.)\nwinremote-mcp --enable-all\n\n# Start with hot reload for development\nwinremote-mcp --reload\n```\n\n### MCP Client Configuration\n\n**For Claude Desktop (`claude_desktop_config.json`):**\n```json\n{\n  \"mcpServers\": {\n    \"winremote\": {\n      \"command\": \"winremote-mcp\",\n      \"args\": [\"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\n**For HTTP MCP clients:**\n```json\n{\n  \"mcpServers\": {\n    \"winremote\": {\n      \"type\": \"streamable-http\", \n      \"url\": \"http://192.168.1.100:8090/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your-secret-key\"\n      }\n    }\n  }\n}\n```\n\n### Auto-Start on Boot\n```bash\n# Create Windows scheduled task\nwinremote-mcp install\n\n# Remove scheduled task  \nwinremote-mcp uninstall\n```\n\n## Security\n\nTools are organized into three risk tiers. By default, only Tier 1-2 tools are enabled.\n\n| Tier | Risk | Default | Examples |\n|------|------|---------|----------|\n| **Tier 1** | Read-only | ✅ Enabled | Snapshot, GetSystemInfo, FileList |\n| **Tier 2** | Interactive | ✅ Enabled | Click, Type, Shortcut, Scrape |\n| **Tier 3** | Destructive / server-side effects | ❌ Disabled | Shell, App, PlaySound, FileWrite |\n\n```bash\n# Enable all tiers (use with caution)\nwinremote-mcp --enable-all\n\n# Always use auth for remote access\nwinremote-mcp --host 0.0.0.0 --auth-key \"your-secret-key\"\n```\n\nSee [SECURITY.md](SECURITY.md) for the full security guide.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| **Desktop** | |\n| Snapshot | Screenshot (JPEG, configurable quality/max_width) + window list + UI elements |\n| AnnotatedSnapshot | Screenshot with numbered labels on interactive elements |\n| OCR | Extract text from screen via OCR (pytesseract or Windows built-in) |\n| ScreenRecord | Record screen activity as animated GIF |\n| PlaySound | Play audio file on Windows host (.wav/.mp3/.ogg/.wma/.m4a, local path or URL) |\n| **Input** | |\n| Click | Mouse click (left/right/middle, single/double/hover) |\n| Type | Type text at coordinates |\n| Scroll | Vertical/horizontal scroll |\n| Move | Move mouse / drag |\n| Shortcut | Keyboard shortcuts |\n| Wait | Pause execution |\n| **Window Management** | |\n| FocusWindow | Bring window to front (fuzzy title match) |\n| MinimizeAll | Show desktop (Win+D) |\n| App | Launch/switch/resize applications |\n| **System** | |\n| Shell | Execute PowerShell commands (with optional cwd) |\n| GetClipboard | Read clipboard |\n| SetClipboard | Write clipboard |\n| ListProcesses | Process list with CPU/memory |\n| KillProcess | Kill process by PID or name |\n| GetSystemInfo | System information |\n| Notification | Windows toast notification |\n| LockScreen | Lock workstation |\n| ReconnectSession | Reconnect disconnected Windows desktop session to console |\n| **File System** | |\n| FileRead | Read file content |\n| FileWrite | Write file content |\n| FileList | List directory contents |\n| FileSearch | Search files by pattern |\n| FileDownload | Download file as base64 (binary) |\n| FileUpload | Upload file from base64 (binary) |\n| **Registry \u0026 Services** | |\n| RegRead | Read Windows Registry value |\n| RegWrite | Write Windows Registry value |\n| ServiceList | List Windows services |\n| ServiceStart | Start a Windows service |\n| ServiceStop | Stop a Windows service |\n| **Scheduled Tasks** | |\n| TaskList | List scheduled tasks |\n| TaskCreate | Create a scheduled task |\n| TaskDelete | Delete a scheduled task |\n| **Network** | |\n| Scrape | Fetch URL content |\n| Ping | Ping a host |\n| PortCheck | Check if a TCP port is open |\n| NetConnections | List network connections |\n| EventLog | Read Windows Event Log entries |\n\n## How It Works\n\n```mermaid\ngraph LR\n    A[\"MCP Client\u003cbr/\u003e(Claude/AI)\"] --\u003e|commands| B[\"WinRemote MCP\u003cbr/\u003eServer\"]\n    B --\u003e|API calls| C[\"Windows APIs\u003cbr/\u003e(Win32/WMI/PS)\"]\n    C --\u003e|results| B\n    B --\u003e|responses| A\n```\n\n**Transport Options:**\n- **stdio**: Direct process communication (ideal for Claude Desktop)\n- **HTTP**: RESTful API with optional authentication (ideal for remote access)\n\n**Core Architecture:**\n1. **Tool Layer**: 40+ Windows automation tools (screenshot, click, type, etc.)\n2. **Task Manager**: Concurrency control and task cancellation\n3. **Transport Layer**: MCP protocol over stdio or HTTP\n4. **Security Layer**: Optional Bearer token authentication\n\n## Working with Non-Standard UI Frameworks\n\n`AnnotatedSnapshot` uses Win32 API to detect UI elements, which doesn't work with **Flutter, Electron, Qt**, or custom-drawn UIs. Three solutions:\n\n| Approach | Setup | GPU | Best For |\n|----------|-------|-----|----------|\n| **Snapshot + Claude Vision** | None | No | Most users — Claude sees the screenshot and clicks |\n| **[UI-TARS Desktop](https://github.com/bytedance/UI-TARS-desktop)** | Medium | 16 GB | Highest accuracy (94.2%), best Chinese UI support |\n| **[OmniMCP](https://github.com/OpenAdaptAI/OmniMCP)** | Medium | 16 GB | Multi-LLM setups (LLM-agnostic) |\n\n**Quick example** — no extra tools needed:\n```\nYou:    \"Take a screenshot with Snapshot, find the Connect button, and click it.\"\nClaude:  1. Calls Snapshot() → sees the Flutter app screenshot\n         2. Vision identifies \"Connect\" button at (520, 340)\n         3. Calls Click(x=520, y=340)\n```\n\nFor the complete guide with setup instructions, architecture diagrams, and comparison benchmarks, see **[docs/vision-guide.md](docs/vision-guide.md)**.\n\n## Troubleshooting / FAQ\n\n### Q: MCP server not starting?\n**A:** Check Python version (requires 3.10+) and ensure no other service is using port 8090:\n```bash\npython --version\nnetstat -an | findstr :8090\n```\n\n### Q: Can't connect from remote machine?\n**A:** Use `--host 0.0.0.0` to bind to all interfaces (default is localhost only):\n```bash\nwinremote-mcp --host 0.0.0.0 --auth-key \"secure-key\"\n```\n\n### Q: Screenshot tool returns empty/black images?\n**A:** Windows may be locked or display turned off. Ensure:\n- Windows is unlocked and display is active\n- No screen saver is running\n- For multi-monitor setups, specify `monitor` parameter\n\n### Q: OCR not working?\n**A:** Install Tesseract OCR engine:\n```bash\nwinget install UB-Mannheim.TesseractOCR\npip install winremote-mcp[ocr]\n```\n\n### Q: Permission errors with registry/services?\n**A:** Run with administrator privileges:\n```bash\n# Right-click Command Prompt → \"Run as administrator\"\nwinremote-mcp\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n```bash\ngit clone https://github.com/dddabtc/winremote-mcp.git\ncd winremote-mcp\npip install -e \".[test]\"\npytest  # Run tests\n```\n\n## Acknowledgments\n\nInspired by [Windows-MCP](https://github.com/CursorTouch/Windows-MCP) by CursorTouch. Thanks for the pioneering work on Windows desktop automation via MCP.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Ready to automate Windows with AI?** ⚡ Install `winremote-mcp` and connect your favorite AI agent to any Windows machine in under 30 seconds.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdddabtc%2Fwinremote-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdddabtc%2Fwinremote-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdddabtc%2Fwinremote-mcp/lists"}