winremote-mcp 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. winremote_mcp-0.2.0/.github/workflows/ci.yml +21 -0
  2. winremote_mcp-0.2.0/.github/workflows/publish.yml +21 -0
  3. winremote_mcp-0.2.0/CHANGELOG.md +24 -0
  4. winremote_mcp-0.2.0/CONTRIBUTING.md +27 -0
  5. winremote_mcp-0.2.0/LICENSE +21 -0
  6. winremote_mcp-0.2.0/PKG-INFO +175 -0
  7. winremote_mcp-0.2.0/README.md +148 -0
  8. winremote_mcp-0.2.0/pyproject.toml +47 -0
  9. winremote_mcp-0.2.0/src/winremote/__init__.py +3 -0
  10. winremote_mcp-0.2.0/src/winremote/__main__.py +838 -0
  11. winremote_mcp-0.2.0/src/winremote/desktop.py +305 -0
  12. winremote_mcp-0.2.0/src/winremote/process_mgr.py +106 -0
winremote_mcp-0.2.0/.github/workflows/ci.yml ADDED
@@ -0,0 +1,21 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [master]
6
+ pull_request:
7
+
8
+ jobs:
9
+ lint:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ matrix:
13
+ python-version: ["3.10", "3.11", "3.12"]
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: actions/setup-python@v5
17
+ with:
18
+ python-version: ${{ matrix.python-version }}
19
+ - run: pip install ruff
20
+ - run: ruff check .
21
+ - run: ruff format --check .
winremote_mcp-0.2.0/.github/workflows/publish.yml ADDED
@@ -0,0 +1,21 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+
7
+ permissions:
8
+ id-token: write
9
+
10
+ jobs:
11
+ publish:
12
+ runs-on: ubuntu-latest
13
+ environment: pypi
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: actions/setup-python@v5
17
+ with:
18
+ python-version: "3.12"
19
+ - run: pip install build
20
+ - run: python -m build
21
+ - uses: pypa/gh-action-pypi-publish@release/v1
winremote_mcp-0.2.0/CHANGELOG.md ADDED
@@ -0,0 +1,24 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.2.0] - 2025-02-08
9
+
10
+ ### Added
11
+
12
+ - Desktop control: screenshot (JPEG compressed), click, type, scroll, keyboard shortcuts
13
+ - Window management: focus by fuzzy title match, minimize-all (Win+D), launch/resize apps
14
+ - Remote management: PowerShell shell with optional `cwd`, clipboard read/write, process list/kill, system info, notifications, lock screen
15
+ - File operations: read, write, list, search
16
+ - Web scraping: fetch URL content via `Scrape` tool
17
+ - Snapshot compression: configurable `quality` (default 75) and `max_width` (default 1920) for JPEG output
18
+ - Health endpoint: `GET /health` returns `{"status":"ok","version":"0.2.0"}`
19
+ - Hot reload: `--reload` flag for development
20
+ - Auto-start: `winremote install` / `winremote uninstall` for Windows scheduled tasks
21
+ - Transport options: stdio (default) and streamable-http
22
+ - Better pywin32 error reporting with explicit messages
23
+
24
+ [0.2.0]: https://github.com/dddabtc/winremote-mcp/releases/tag/v0.2.0
winremote_mcp-0.2.0/CONTRIBUTING.md ADDED
@@ -0,0 +1,27 @@
1
+ # Contributing
2
+
3
+ Thanks for your interest in winremote-mcp!
4
+
5
+ ## Workflow
6
+
7
+ 1. **Fork** the repo and clone locally
8
+ 2. **Branch** from `master`: `git checkout -b feat/my-feature`
9
+ 3. **Install dev deps**: `pip install -e ".[dev]"`
10
+ 4. **Lint**: `ruff check . && ruff format --check .`
11
+ 5. **Commit** using [Conventional Commits](https://www.conventionalcommits.org/):
12
+ - `feat: add new tool`
13
+ - `fix: handle missing window`
14
+ - `chore: update deps`
15
+ 6. **Push** and open a **Pull Request** against `master`
16
+ 7. PRs are **squash merged**
17
+
18
+ ## Development
19
+
20
+ ```bash
21
+ # Run with hot reload
22
+ winremote-mcp --reload
23
+ ```
24
+
25
+ ## Code Style
26
+
27
+ This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting. CI will check automatically.
winremote_mcp-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 winremote contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
winremote_mcp-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,175 @@
1
+ Metadata-Version: 2.4
2
+ Name: winremote-mcp
3
+ Version: 0.2.0
4
+ Summary: Windows Remote MCP Server - control Windows desktops via MCP protocol
5
+ Author: winremote contributors
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Keywords: automation,desktop,mcp,remote,windows
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Operating System :: Microsoft :: Windows
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Topic :: Desktop Environment
13
+ Requires-Python: >=3.10
14
+ Requires-Dist: click>=8.0.0
15
+ Requires-Dist: fastmcp>=2.0.0
16
+ Requires-Dist: markdownify>=0.13.0
17
+ Requires-Dist: pillow>=10.0.0
18
+ Requires-Dist: psutil>=5.9.0
19
+ Requires-Dist: pyautogui>=0.9.54
20
+ Requires-Dist: python-dotenv>=1.0.0
21
+ Requires-Dist: pywin32>=306; sys_platform == 'win32'
22
+ Requires-Dist: tabulate>=0.9.0
23
+ Requires-Dist: thefuzz[speedup]>=0.20.0
24
+ Provides-Extra: dev
25
+ Requires-Dist: ruff>=0.9.0; extra == 'dev'
26
+ Description-Content-Type: text/markdown
27
+
28
+ # winremote-mcp
29
+
30
+ [![CI](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml)
31
+ [![PyPI](https://img.shields.io/pypi/v/winremote-mcp)](https://pypi.org/project/winremote-mcp/)
32
+ [![Python](https://img.shields.io/pypi/pyversions/winremote-mcp)](https://pypi.org/project/winremote-mcp/)
33
+
34
+ A Windows Remote MCP Server — control Windows desktops via the [Model Context Protocol](https://modelcontextprotocol.io/).
35
+
36
+ Built with [FastMCP](https://github.com/jlowin/fastmcp). Runs **on the Windows machine** you want to control.
37
+
38
+ ## Features
39
+
40
+ - **Desktop Control** — screenshot (JPEG compressed), click, type, scroll, keyboard shortcuts
41
+ - **Window Management** — focus, minimize-all, launch/resize apps
42
+ - **Remote Management** — PowerShell shell (with `cwd`), clipboard, processes, system info, notifications
43
+ - **File Operations** — read, write, list, search files
44
+ - **Health Endpoint** — `GET /health` returns `{"status":"ok","version":"0.2.0"}`
45
+ - **Hot Reload** — `--reload` flag for development
46
+ - **Auto-Start** — `winremote install` / `winremote uninstall` for Windows scheduled tasks
47
+
48
+ ## Installation
49
+
50
+ ```bash
51
+ # From PyPI (once published)
52
+ pip install winremote-mcp
53
+
54
+ # From source
55
+ pip install .
56
+
57
+ # With uv
58
+ uv pip install .
59
+ ```
60
+
61
+ > **PyPI publishing**: This repo uses GitHub Actions with [trusted publishers](https://docs.pypi.org/trusted-publishers/). To enable, configure PyPI trusted publisher for the `dddabtc/winremote-mcp` repo, workflow `publish.yml`, environment `pypi`.
62
+
63
+ ## Usage
64
+
65
+ ### stdio transport
66
+ ```bash
67
+ winremote-mcp
68
+ # or
69
+ uv run winremote-mcp
70
+ ```
71
+
72
+ ### Streamable HTTP transport (default, for remote access)
73
+ ```bash
74
+ winremote-mcp --transport streamable-http --host 0.0.0.0 --port 8090
75
+ ```
76
+
77
+ ### With hot reload (development)
78
+ ```bash
79
+ winremote-mcp --reload
80
+ ```
81
+
82
+ ### Health check
83
+ ```bash
84
+ curl http://localhost:8090/health
85
+ # {"status":"ok","version":"0.2.0"}
86
+ ```
87
+
88
+ ### Auto-start (Windows scheduled task)
89
+ ```bash
90
+ # Create scheduled task to start on boot
91
+ winremote-mcp install
92
+
93
+ # Remove scheduled task
94
+ winremote-mcp uninstall
95
+ ```
96
+
97
+ ### MCP Client Config
98
+
99
+ **stdio:**
100
+ ```json
101
+ {
102
+ "mcpServers": {
103
+ "windows-remote": {
104
+ "command": "uv",
105
+ "args": ["run", "winremote-mcp"]
106
+ }
107
+ }
108
+ }
109
+ ```
110
+
111
+ **streamable-http:**
112
+ ```json
113
+ {
114
+ "mcpServers": {
115
+ "windows-remote": {
116
+ "type": "streamable-http",
117
+ "url": "http://<windows-ip>:8090/mcp"
118
+ }
119
+ }
120
+ }
121
+ ```
122
+
123
+ ## What's New in v0.2.0
124
+
125
+ - **Snapshot compression**: Returns JPEG instead of PNG. Configurable `quality` (default 75) and `max_width` (default 1920) params. Significantly reduces image size.
126
+ - **Health endpoint**: `GET /health` returns JSON status — useful for monitoring and load balancers.
127
+ - **Shell cwd parameter**: Optional `cwd` param to run commands in a specific directory.
128
+ - **Better pywin32 error reporting**: Explicit error messages when pywin32 is missing instead of silent failures.
129
+ - **Hot reload**: `--reload` flag passes through to uvicorn for development.
130
+ - **Install/uninstall commands**: `winremote install` creates a Windows scheduled task for auto-start on boot.
131
+
132
+ ## Tools
133
+
134
+ | Tool | Description |
135
+ |------|-------------|
136
+ | Snapshot | Screenshot (JPEG, configurable quality/max_width) + window list + UI elements |
137
+ | Click | Mouse click (left/right/middle, single/double/hover) |
138
+ | Type | Type text at coordinates |
139
+ | Scroll | Vertical/horizontal scroll |
140
+ | Move | Move mouse / drag |
141
+ | Shortcut | Keyboard shortcuts |
142
+ | Wait | Pause execution |
143
+ | FocusWindow | Bring window to front (fuzzy title match) |
144
+ | MinimizeAll | Show desktop (Win+D) |
145
+ | App | Launch/switch/resize applications |
146
+ | Shell | Execute PowerShell commands (with optional cwd) |
147
+ | GetClipboard | Read clipboard |
148
+ | SetClipboard | Write clipboard |
149
+ | ListProcesses | Process list with CPU/memory |
150
+ | KillProcess | Kill process by PID or name |
151
+ | GetSystemInfo | System information |
152
+ | Notification | Windows toast notification |
153
+ | LockScreen | Lock workstation |
154
+ | Scrape | Fetch URL content |
155
+ | FileRead | Read file content |
156
+ | FileWrite | Write file content |
157
+ | FileList | List directory contents |
158
+ | FileSearch | Search files by pattern |
159
+
160
+ ## Requirements
161
+
162
+ - Windows 10/11
163
+ - Python >= 3.10
164
+
165
+ ## Acknowledgments
166
+
167
+ Inspired by [Windows-MCP](https://github.com/CursorTouch/Windows-MCP) by CursorTouch. Thanks for the pioneering work on Windows desktop automation via MCP.
168
+
169
+ ## Contributing
170
+
171
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
172
+
173
+ ## License
174
+
175
+ MIT
winremote_mcp-0.2.0/README.md ADDED
@@ -0,0 +1,148 @@
1
+ # winremote-mcp
2
+
3
+ [![CI](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/winremote-mcp)](https://pypi.org/project/winremote-mcp/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/winremote-mcp)](https://pypi.org/project/winremote-mcp/)
6
+
7
+ A Windows Remote MCP Server — control Windows desktops via the [Model Context Protocol](https://modelcontextprotocol.io/).
8
+
9
+ Built with [FastMCP](https://github.com/jlowin/fastmcp). Runs **on the Windows machine** you want to control.
10
+
11
+ ## Features
12
+
13
+ - **Desktop Control** — screenshot (JPEG compressed), click, type, scroll, keyboard shortcuts
14
+ - **Window Management** — focus, minimize-all, launch/resize apps
15
+ - **Remote Management** — PowerShell shell (with `cwd`), clipboard, processes, system info, notifications
16
+ - **File Operations** — read, write, list, search files
17
+ - **Health Endpoint** — `GET /health` returns `{"status":"ok","version":"0.2.0"}`
18
+ - **Hot Reload** — `--reload` flag for development
19
+ - **Auto-Start** — `winremote install` / `winremote uninstall` for Windows scheduled tasks
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ # From PyPI (once published)
25
+ pip install winremote-mcp
26
+
27
+ # From source
28
+ pip install .
29
+
30
+ # With uv
31
+ uv pip install .
32
+ ```
33
+
34
+ > **PyPI publishing**: This repo uses GitHub Actions with [trusted publishers](https://docs.pypi.org/trusted-publishers/). To enable, configure PyPI trusted publisher for the `dddabtc/winremote-mcp` repo, workflow `publish.yml`, environment `pypi`.
35
+
36
+ ## Usage
37
+
38
+ ### stdio transport
39
+ ```bash
40
+ winremote-mcp
41
+ # or
42
+ uv run winremote-mcp
43
+ ```
44
+
45
+ ### Streamable HTTP transport (default, for remote access)
46
+ ```bash
47
+ winremote-mcp --transport streamable-http --host 0.0.0.0 --port 8090
48
+ ```
49
+
50
+ ### With hot reload (development)
51
+ ```bash
52
+ winremote-mcp --reload
53
+ ```
54
+
55
+ ### Health check
56
+ ```bash
57
+ curl http://localhost:8090/health
58
+ # {"status":"ok","version":"0.2.0"}
59
+ ```
60
+
61
+ ### Auto-start (Windows scheduled task)
62
+ ```bash
63
+ # Create scheduled task to start on boot
64
+ winremote-mcp install
65
+
66
+ # Remove scheduled task
67
+ winremote-mcp uninstall
68
+ ```
69
+
70
+ ### MCP Client Config
71
+
72
+ **stdio:**
73
+ ```json
74
+ {
75
+ "mcpServers": {
76
+ "windows-remote": {
77
+ "command": "uv",
78
+ "args": ["run", "winremote-mcp"]
79
+ }
80
+ }
81
+ }
82
+ ```
83
+
84
+ **streamable-http:**
85
+ ```json
86
+ {
87
+ "mcpServers": {
88
+ "windows-remote": {
89
+ "type": "streamable-http",
90
+ "url": "http://<windows-ip>:8090/mcp"
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
96
+ ## What's New in v0.2.0
97
+
98
+ - **Snapshot compression**: Returns JPEG instead of PNG. Configurable `quality` (default 75) and `max_width` (default 1920) params. Significantly reduces image size.
99
+ - **Health endpoint**: `GET /health` returns JSON status — useful for monitoring and load balancers.
100
+ - **Shell cwd parameter**: Optional `cwd` param to run commands in a specific directory.
101
+ - **Better pywin32 error reporting**: Explicit error messages when pywin32 is missing instead of silent failures.
102
+ - **Hot reload**: `--reload` flag passes through to uvicorn for development.
103
+ - **Install/uninstall commands**: `winremote install` creates a Windows scheduled task for auto-start on boot.
104
+
105
+ ## Tools
106
+
107
+ | Tool | Description |
108
+ |------|-------------|
109
+ | Snapshot | Screenshot (JPEG, configurable quality/max_width) + window list + UI elements |
110
+ | Click | Mouse click (left/right/middle, single/double/hover) |
111
+ | Type | Type text at coordinates |
112
+ | Scroll | Vertical/horizontal scroll |
113
+ | Move | Move mouse / drag |
114
+ | Shortcut | Keyboard shortcuts |
115
+ | Wait | Pause execution |
116
+ | FocusWindow | Bring window to front (fuzzy title match) |
117
+ | MinimizeAll | Show desktop (Win+D) |
118
+ | App | Launch/switch/resize applications |
119
+ | Shell | Execute PowerShell commands (with optional cwd) |
120
+ | GetClipboard | Read clipboard |
121
+ | SetClipboard | Write clipboard |
122
+ | ListProcesses | Process list with CPU/memory |
123
+ | KillProcess | Kill process by PID or name |
124
+ | GetSystemInfo | System information |
125
+ | Notification | Windows toast notification |
126
+ | LockScreen | Lock workstation |
127
+ | Scrape | Fetch URL content |
128
+ | FileRead | Read file content |
129
+ | FileWrite | Write file content |
130
+ | FileList | List directory contents |
131
+ | FileSearch | Search files by pattern |
132
+
133
+ ## Requirements
134
+
135
+ - Windows 10/11
136
+ - Python >= 3.10
137
+
138
+ ## Acknowledgments
139
+
140
+ Inspired by [Windows-MCP](https://github.com/CursorTouch/Windows-MCP) by CursorTouch. Thanks for the pioneering work on Windows desktop automation via MCP.
141
+
142
+ ## Contributing
143
+
144
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
145
+
146
+ ## License
147
+
148
+ MIT
winremote_mcp-0.2.0/pyproject.toml ADDED
@@ -0,0 +1,47 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "winremote-mcp"
7
+ version = "0.2.0"
8
+ description = "Windows Remote MCP Server - control Windows desktops via MCP protocol"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.10"
12
+ authors = [{ name = "winremote contributors" }]
13
+ keywords = ["mcp", "windows", "remote", "automation", "desktop"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Operating System :: Microsoft :: Windows",
17
+ "Programming Language :: Python :: 3",
18
+ "Topic :: Desktop Environment",
19
+ ]
20
+ dependencies = [
21
+ "fastmcp>=2.0.0",
22
+ "pyautogui>=0.9.54",
23
+ "psutil>=5.9.0",
24
+ "pywin32>=306; sys_platform == 'win32'",
25
+ "Pillow>=10.0.0",
26
+ "click>=8.0.0",
27
+ "python-dotenv>=1.0.0",
28
+ "thefuzz[speedup]>=0.20.0",
29
+ "tabulate>=0.9.0",
30
+ "markdownify>=0.13.0",
31
+ ]
32
+
33
+ [project.scripts]
34
+ winremote-mcp = "winremote.__main__:cli"
35
+
36
+ [project.optional-dependencies]
37
+ dev = ["ruff>=0.9.0"]
38
+
39
+ [tool.ruff]
40
+ target-version = "py310"
41
+ line-length = 120
42
+
43
+ [tool.ruff.lint]
44
+ select = ["E", "F", "I", "W"]
45
+
46
+ [tool.hatch.build.targets.wheel]
47
+ packages = ["src/winremote"]
winremote_mcp-0.2.0/src/winremote/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """winremote-mcp: Windows Remote MCP Server."""
2
+
3
+ __version__ = "0.2.0"