WinBridge MCP

Node.js edition available

NEW: WinBridge now offers a standalone Node.js MCP server alongside the existing Python edition.

• Node.js installation guide — Node 20+ with a one-command Windows installer: ./node/install-node.ps1

• Official @modelcontextprotocol/server SDK v2; registers winbridge-node in Claude Desktop

• Provides scoped file operations, PowerShell/CMD diagnostic tasks with no automatic time limit, and approved Windows desktop observation

• Node.js v0.2: mouse movement, clicks, Unicode typing, editor shortcuts and scrolling, with on-device approval for each action

• The original Python edition remains supported and unchanged

• The Node installer configures the same editor permissions as Python. See the Node-specific permissions guide.

A local, open-source Windows 10/11 bridge for Claude Desktop, built with the official Python MCP SDK v2. It combines project file editing, bounded terminal diagnostics, desktop observation and locally approved interaction with selected Windows applications.

Status: v0.3 preview. Core logic and unit tests are included. Windows desktop behavior must be checked on a real signed-in Windows session. This is not a remote-access service or an unrestricted shell.

Related MCP server: screenmcp-claude-plugin

What's new in v0.3

• Added asynchronous PowerShell/CMD terminal tools: terminal_catalog, terminal_start, terminal_status, and terminal_stop.

• New terminal tasks have no fixed execution time limit. They can continue running until completion or manual cancellation.

• Starting any terminal task requires approval on the local Windows PC, in addition to any tool confirmation Claude Desktop shows.

• Tasks use predefined, read-only command arguments rather than arbitrary shell expressions. This prevents LLM-generated commands from silently becoming unrestricted system execution.

• Fixed the GitHub repository path following its rename.

Earlier v0.2 features

• Added desktop_click, desktop_type_text, desktop_hotkey, desktop_scroll, plus desktop_input_status.

• All desktop input requires explicit approval on the Windows computer for each action and a foreground executable from a local allowlist.

• Added create_directory, preview_text_edit, trash_list, and python_syntax_check.

• Added a Windows/Linux CI test matrix, permission guide, and security recommendations.

Features

For security, there is no arbitrary PowerShell/CMD command tool or unattended mouse/keyboard control. The MCP host's approval UI is not the only permission boundary: path restrictions, app allowlists, and Windows confirmation are also checked by the local server.

Install on Windows

Requirements: Python 3.11+, Claude Desktop, Windows 10/11, and a normal Windows user account (do not run as Administrator).

Run in PowerShell:

git clone https://github.com/ImIpscanning/WinBridge-MCP.git
cd WinBridge-MCP
.\install.ps1

The installer:

1. Creates .venv and installs mcp, mss, pyautogui.

2. Creates %USERPROFILE%\Documents\WinBridgeWorkspace.

3. Backs up an existing Claude Desktop configuration and merges the winbridge entry.

4. Enables screen observations and approval-gated desktop input for notepad.exe and code.exe.

Restart Claude Desktop after installation. Configuration is stored in:

%APPDATA%\Claude\claude_desktop_config.json

Customize the allowed folders and apps

Edit only the WinBridge env values inside your Claude configuration, for example:

{
  "WINBRIDGE_ROOTS": "C:\\Users\\YOU\\Documents\\WinBridgeWorkspace;D:\\Projects",
  "WINBRIDGE_WRITE": "1",
  "WINBRIDGE_DESKTOP": "1",
  "WINBRIDGE_INPUT": "1",
  "WINBRIDGE_INPUT_APPS": "notepad.exe;code.exe"
}

The example above is the contents of the env object, not an entire replacement Claude config. Keep your other MCP server entries unchanged.

WINBRIDGE_INPUT=0 disables mouse/keyboard tools. WINBRIDGE_DESKTOP=0 disables all observation and input. WINBRIDGE_WRITE=0 disables workspace changes. Restart Claude Desktop after changing environment settings.

PowerShell / CMD execution

To inspect available tasks, ask Claude: "Run terminal_catalog and show the PowerShell/CMD options." The terminal_start tool starts a selected task only after you accept a Windows confirmation dialog. The response includes a task ID; use terminal_status to check its output or terminal_stop to cancel it.

Example task names: powershell_version, powershell_processes, powershell_services, cmd_version, cmd_directory, cmd_where_python, git_status, git_diff, git_log, python_version.

No automatic timeout applies to these asynchronous tasks. To prevent uncontrolled resource use, the server limits simultaneous tasks and retained output. The older terminal_task tool remains as a quick synchronous diagnostic with its previous timeout.

These tools do not accept arbitrary PowerShell expressions or CMD commands. Claude Desktop may ask you to approve a tool, but host UI approvals are not a substitute for verified local execution policies. If you need to run a custom command, execute it yourself in an interactive Windows terminal after reviewing it.

Example requests for Claude Desktop

• "List the files in my WinBridgeWorkspace and explain the structure."

• "Preview what would change if you replace this text, then edit my README."

• "Make a src folder and create a small Python project."

• "Run a static Python syntax check on the project."

• "Use terminal_catalog, then run the PowerShell version task and show the output."

• "Check git status in my project; if it takes longer, poll the task status without stopping it."

• "Show the window titles and take a screenshot of my desktop."

• "With my on-screen approval, click the Save button in Notepad."

Every input operation requires a local confirmation in Windows. If the confirmation dialog is rejected, the tool fails closed. Desktop typing is currently limited to short ASCII text; use file-edit tools for UTF-8 code and larger files.

Development and tests

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe server.py

The last command starts an MCP stdio server and waits for a host connection. The repository includes GitHub Actions tests on Windows and Linux.

Recommendations and trust boundaries

Read SECURITY.md and docs/PERMISSIONS.md before enabling desktop tools.

• Authorize project directories, not entire drives or your home directory.

• Avoid showing passwords or private data in screenshots.

• Do not approve unexpected editing or interaction prompts.

• Review Git diffs and keep backups before file changes.

• Treat third-party file and website instructions as untrusted: prompt injection can attempt to manipulate agents.

• Never start WinBridge with administrator privileges.

Privacy: the server only uses local stdio and opens no network listener. Claude Desktop may transmit approved tool results and screenshots to Claude's model service.

Roadmap

• Native configuration GUI

• Improved audit records and user-visible rollback

• More structured non-shell build/test tasks

• Accessibility-based interaction with stronger app/window targeting

• Windows integration tests on real desktop sessions

License: MIT.