Skip to main content
Glama
README.md
# win-mcp for LM Studio

A Windows MCP server for inspecting a selected application window, bounded
window-relative interaction, standard Save/Open dialogs and local text-to-speech.
LM Studio is the primary setup path. Claude Desktop is also supported through
stdio; see [the Claude guide](Docs/CLAUDE-DESKTOP.md).

## Requirements

- Windows desktop session with the target application running.
- Node.js 22 or newer.
- Python 3.11 or newer and Pillow (requirements.txt).
- LM Studio with local MCP support and a model able to call tools.
- This is an unofficial integration; no affiliation or certification is implied.

## Install

Extract the source release to a writable folder. The examples use
C:/MCP/win-mcp; replace this with your actual absolute path.

~~~powershell
cd C:\MCP\win-mcp
npm ci --ignore-scripts
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
Copy-Item config.example.json config.json
New-Item -ItemType Directory -Force downloads | Out-Null
~~~

Set executor.pythonPath in config.json to the absolute .venv Python executable,
or use WIN_MCP_PYTHON in the client entry. Generic defaults permit dialog output
only inside this installation's downloads folder. Add the folders you want
explicitly; relative configured paths are resolved against the server folder.

config.json is local and excluded from releases. If it is absent, the server
uses config.example.json. An explicit WIN_MCP_CONFIG points to an alternative
configuration and fails if that file cannot be read. Nothing edits your host
application's configuration automatically.

## Connect LM Studio

Merge examples/lmstudio-mcp.json into your LM Studio mcp.json, replace the
installation/interpreter paths, and make win-mcp available to the chat.
Use the in-app MCP configuration editor; on Windows its file is normally
%USERPROFILE%/.lmstudio/mcp.json. See [LM Studio setup](Docs/LM-STUDIO.md).

Start with health_check and list_windows. Then select_target_window(hwnd) and
capture_target_window before requesting input. Active-window input tools are
disabled; use selected-window coordinates from a recent capture.

## Capabilities

| Group | Examples |
|---|---|
| Diagnostics | health_check, server_status, list_windows, get_active_window |
| Target selection | select_target_window, get_target_window, clear_target_window |
| Observation | capture_target_window, capture_target_with_related_windows, get_cursor_position_target_window |
| Input | click_target_window, scroll_target_window, type_text_target_window, send_key_target_window |
| Capture after input | click_target_window_and_capture, scroll_target_window_and_capture |
| Dialogs | detect_file_dialog, set_file_dialog_path, confirm_file_dialog, cancel_file_dialog |
| Speech | speak_text using Windows SAPI |

Create a STOP file in the installation folder to stop queued/new tool work
except health_check. It is not a guaranteed interrupt for an action already
executing. Remove it when ready to resume.

Windows privilege boundaries still apply. A standard-user server may fail to
interact with an elevated target. This release does not bypass UAC or grant
administrative access. Captures can contain occluding windows; confirm the
returned image before acting. Coordinate validation is not a visual-identity
guarantee.

## Verification and release

~~~powershell
npm test
npm run release
~~~

npm test runs validation/health checks without clicking, typing, playing speech
or launching browsers. Real desktop workflows need separate user-controlled tests.
See [release procedure](Docs/RELEASING.md) and [security notes](Docs/SECURITY.md).

Stdio is the default. The optional HTTP entry point is advanced, unauthenticated
and intended for loopback only; see the security notes before using it.

Licence: [MIT](LICENSE).