Reach MCP

PC control for ChatGPT and Claude chats

An open-source Windows control server for MCP clients. Its 30 tools combine screenshots, mouse and keyboard input with direct file access, code search, exact patches, and managed terminal jobs through stdio or authenticated loopback HTTP. An optional GitHub OAuth relay connects remote clients such as ordinary ChatGPT Chat. ChatGPT has been tested end to end; the Claude Chat OAuth callback is supported but has not yet been verified in a live Claude Chat session.

The server is designed for a dedicated Windows VM. Desktop control runs with the logged-in user's privileges; it is not a sandbox.

Approval controls

Choose where approvals happen when starting the server:

For remote Chat use with approvals only in the chat, start the relay with:

.\web\run-web.ps1 -ApprovalPolicy client

In ChatGPT, select Always ask in the Reach MCP plugin's permissions. You can then approve tool requests from the chat without being at the VM. Other clients must provide and enforce their own permission controls. Keep -ApprovalPolicy client in the startup task's command if you want this choice to survive restarts.

Client policy trusts the connected client to obtain consent. MCP does not provide Reach MCP with cryptographic proof that a human approved each call, so the server cannot verify the chat's permission prompt. OAuth owner authentication, native HTTP bearer authentication, loopback listeners, disabled-tool rules, audit logging, and input kill switches still apply. See SECURITY.md.

For an additional local decision, use local policy and open the controls from the Windows desktop:

.\scripts\open-controls.ps1

The local control panel offers three modes:

Temporary local modes expire back to Ask; changing modes cancels pending requests. “Low risk” means an explicit tool allowlist, not AI judgment of an action's intent. Screenshots and window information can still contain private data. Client policy is a separate startup policy, not a temporary Full access mode.

The panel and its private URL are local-only. Do not expose its port, share its URL, or add it to the public relay. With local policy, both client and local prompts can apply.

Related MCP server: Computer-Controller-Bridg

Requirements and setup

• Windows 10 or 11 with an interactive desktop

• Python 3.12

• A normal, non-administrator user account

Clone the project, then run setup:

git clone https://github.com/whyaaronbailey/reach-mcp.git
cd reach-mcp

From the project directory:

.\scripts\setup.ps1
# Or supply a Python executable:
.\scripts\setup.ps1 -Python 'C:\Path\To\Python312\python.exe'

Setup creates .venv, installs the project and development dependencies, and runs the unit tests. It does not register an MCP client, publish a network endpoint, or create a startup task.

Start a stdio server with the default local approval policy:

.\.venv\Scripts\reach-mcp.exe --client local

See clients/README.md for client registration and loopback HTTP. For remote Chat, follow web/README.md.

Tools

Action tools can return a fresh screenshot with screenshot: true. Coordinates default to the most recent screenshot's pixel space; the server maps the downscaled image to physical pixels. Use coordinate_space: "screen" for raw desktop coordinates. Capture again after the target moves. Coordinate actions waiting for approval reject a changed screenshot mapping.

Unicode input uses conservative pacing for Windows text controls and checks input kill switches between characters. The default limit is 500 characters per call; use an explicitly approved clipboard paste for longer text. Verify the resulting text in the target application.

UI Automation element snapshots and actions are not implemented. The current tool surface uses screenshots and Windows input APIs. The proposed UIA-first/screenshot-fallback design remains a roadmap item.

Files and terminal

Call reach_get_capabilities for this installation's workspace, local roots and limits. The default file roots are the project/state folder and current user's home.

Read an existing file first, then pass its SHA256 to edits, moves and deletion. Changed files are rejected instead of overwritten. New files require create: true. UTF-8 and BOM-marked UTF-16 are supported. Replacements and patches preserve BOM/newlines. Patches use standard unified ---, +++ and @@ headers, with an expected_sha256 path-to-hash map (null for new files). Multi-file patches validate all hunks and attempt rollback on I/O failure; they are not an OS-level transaction. Recursive deletion, shares, device paths, symlinks and junctions are refused by the file tools.

For commands, specify cwd and optionally shell: "program" with an argv array. Save job_id, poll using next_cursor, and inspect exit_code, output_complete, has_more and truncation flags. Jobs have runtime, count and retained-output limits. Commands and descendants are terminated on cancellation, timeout, pause, server shutdown or parent exit. Failed or cancelled commands can leave file changes; inspect before retrying.

Commands run as the normal Windows user and can access that user's files and network beyond the first-class file roots: this is not a shell sandbox. Credential-like environment variables are removed from children; credential files remain subject to Windows account permissions. File/terminal tools work while Windows is locked; desktop input and screenshots still need an interactive session.

Reach does not call an AI model to execute these tools. See Usage audit for Chat versus Work/Codex accounting and an isolated verification procedure.

Safety and configuration

Copy config.example.toml to config.toml to change limits, disable tools, or restrict application launch.

A source checkout keeps configuration, audit logs, pause state, and private panel state in the project directory. An installed wheel uses %LOCALAPPDATA%\ReachMCP instead. Set REACH_MCP_HOME before starting the server to choose a different writable private directory. Relative configuration paths resolve from that directory.

• Move the mouse to the top-left corner or run scripts\pause.ps1 to block desktop input, file mutations and new commands, and stop active managed jobs. Run scripts\resume.ps1 to remove the file-based pause. These input kill switches do not block reads.

• logs\audit.jsonl records tool calls. Typed and clipboard text arguments are redacted by default. Developer payloads, paths, commands and stdin are always redacted; file contents and command output are never audit logged. Each call has a unique event ID.

• Native HTTP binds only to loopback and requires a bearer token. Never expose that listener directly.

• The OAuth relay admits exactly one configured immutable GitHub user ID and exposes a fixed tool allowlist.

• Run without elevation. UAC, the lock screen, and higher-integrity windows are outside the supported desktop.

• Power off or firewall the VM to remove access independently of this software.

Verification

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe scripts\smoke_test.py
.\.venv\Scripts\python.exe scripts\smoke_test.py --interactive

Smoke tests access the actual desktop and require approval. They start a separate temporary server in Ask mode. For a deliberate unattended test, add --approve-test-calls to authorize only that isolated server for 300 seconds through its normal owner API; this does not change a running deployment. The interactive test opens a unique Notepad document, verifies Unicode input, restores the clipboard when the connection remains available, and closes its test document. Run it on a disposable desktop with no sensitive clipboard contents.

See STATUS.md for implementation status and CONTRIBUTING.md for development.

License

MIT. See LICENSE. Dependency licenses remain with their respective projects.