DeskMCP

DeskMCP

DeskMCP is an open-source local-first MCP policy gateway that gives ChatGPT controlled access to local files, terminal sessions, and Windows desktop UI. It runs policy enforcement on your computer, exposes a stable MCP tool surface, and connects through an OpenAI Tunnel while keeping the local MCP endpoint bound to 127.0.0.1.

The default profile is Read-only. Filesystem access is scoped to a workspace you choose locally, sensitive paths are excluded before search, and elevated process capabilities are session-owned rather than arbitrary PID control.

Personal open-source project by edmen12.

Why DeskMCP?

Local-first	The Gateway and policy enforcement run on your computer.
Workspace scoped	Safe profiles keep file tools inside the folder you explicitly select.
Secure by default	First run starts in Read-only mode; Full Control and Fully Unlocked are never persisted.
Easy to install	The self-contained Setup does not require Node.js, npm, .NET, Git, or a source checkout.

Product preview

The tray Control Panel shows Gateway/Tunnel health, the active permission profile, the selected workspace, Windows startup settings, and Tunnel configuration without exposing secrets.

Windows quick start

1. Download DeskMCP-Setup-<version>.exe from the latest GitHub Release and run it.
2. Choose the workspace DeskMCP may access.
3. In OpenAI Platform, create a Tunnel and copy its Tunnel ID and Runtime API Key into First Run.
4. In ChatGPT open Plugins → New plugin.
5. Use Name: DeskMCP, Connection: Tunnel, Auth: No auth.
6. Select the Tunnel, check I understand and want to continue, then Scan tools.

Expected result: 16 DeskMCP tools.

The Runtime API Key is protected with Windows DPAPI and is not written to settings.json. Secret writes are verified by immediate DPAPI readback; settings use atomic replacement with a recoverable backup. You can skip Tunnel setup during First Run and configure it later.

Architecture

ChatGPT
  ↕ OpenAI Tunnel
DeskMCP Gateway  (127.0.0.1:8765)
  ↕ local policy enforcement
  ├─ Desktop Commander
  │   ↳ selected workspace
  │   ↳ Gateway-owned process sessions
  └─ Windows Computer Use backend
      ↳ Microsoft WinApp CLI / UI Automation / screenshot / input

The Tunnel provides the remote transport. The local Gateway checks policy before every filesystem, process, or computer-use action. Windows Computer Use is packaged as a pinned backend behind DeskMCP's own stable MCP schema, so backend changes do not become remote API changes.

Permission profiles

• Read — default; read, list, metadata and bounded search only inside the selected Workspace.
• Write — adds guarded create/edit/write/move operations inside the selected Workspace.
• Full — session-only; keeps the Workspace filesystem boundary and adds terminal/process sessions plus Windows Computer Use under the current Windows user permissions.
• Unlock (fully-unlocked) — session-only; disables DeskMCP Workspace, sensitive-path and fresh-observation file guards and also permits explicitly requested system-wide key injection. Windows ACL/UAC and Secure Desktop remain host boundaries.

Full and Unlock are never persisted. Restarting DeskMCP returns to the last safe persisted profile: Read or Write. Neither profile bypasses Windows ACL/UAC or any remote-client safety policy.

Tool surface

DeskMCP currently exposes a stable 16-tool MCP surface:

desktop_policy_status
desktop_read_file
desktop_list_directory
desktop_get_file_info
desktop_search
desktop_create_directory
desktop_write_file
desktop_edit_file
desktop_move_file
desktop_start_process
desktop_read_process
desktop_interact_process
desktop_terminate_process
desktop_ui_windows
desktop_ui_snapshot
desktop_ui_action

The schemas stay discoverable across profiles so the remote connection remains stable. Discoverable does not mean permitted: every invocation is still checked by the local DeskMCP policy before it can execute.

Windows Computer Use is UI Automation first. desktop_ui_snapshot returns a short-lived opaque computer_observation_id; every desktop_ui_action must consume a fresh observation, and any action invalidates sibling observations for that window so concurrent agents cannot keep acting from stale UI state. GUI mutations are serialized process-wide. Screenshot capture is optional and returned as MCP image/png; use it when visual context is needed instead of paying the image cost on every step. See docs/COMPUTER_USE.md.

On Windows, window_mode controls only whether the CMD/PowerShell console itself is hidden or visible. It is independent from privilege elevation. window_mode: "hidden" remains the default for background agent work; use window_mode: "visible" only when the local user should see and interact with the console window. Visible sessions take interactive keyboard input from their Windows console instead of desktop_interact_process.

elevation: "admin" uses the Windows runas broker and always relies on the normal local UAC approval flow. It is valid with either window mode: hidden + admin shows the standard UAC prompt and, after approval, runs the administrator process without an extra CMD/PowerShell window; visible + admin shows UAC and then opens the visible administrator console. UAC cancellation or denial is returned as an error; DeskMCP does not bypass UAC.

Security model

• Gateway HTTP binds only to 127.0.0.1:8765.
• In Read, Write and Full, allowed filesystem access is restricted to the locally selected Workspace and lexical/canonical path checks block symlink/junction escapes.
• Sensitive paths such as .env, .npmrc, .pypirc, .netrc, .ssh, .gnupg, and .aws/credentials are denied by default, and search excludes them before Desktop Commander/ripgrep reads candidates.
• In Read/Write/Full, desktop_read_file issues a one-time opaque observation_id. Editing, moving, or overwriting an existing file must present the matching fresh capability; capabilities are path/version-bound, single-use, bounded to 1024 entries, and same-path mutations are serialized so concurrent agents cannot silently overwrite each other from the same observed version.
• Unlock intentionally disables those three DeskMCP filesystem protections for the current session. Audit remains enabled and Windows account permissions remain the final local boundary.
• Process tools use opaque Gateway-owned session IDs instead of exposing arbitrary Windows PID control. Capacity counts active sessions plus in-flight start reservations, so no more than 32 owned sessions can be active/starting at once. Desktop Commander's own list_sessions is the active-session source of truth (rather than OS PID liveness guesses); completed-session capabilities remain readable in bounded history, any later reuse of the same OS PID invalidates older capabilities for that PID, and Gateway shutdown cleans up owned live sessions.
• Computer Use exposes opaque window_id capabilities rather than HWND/PID targets. A fresh computer_observation_id is required for every action, observations expire after 30 seconds and are one-time, and the first action on a window invalidates sibling observations from the same UI state.
• Computer Use is available only in session-only Full Control or Fully Unlocked. It does not bypass Windows ACL/UAC, the lock screen, or UAC Secure Desktop. System-wide key injection requires Fully Unlocked; the MCP surface does not expose WinApp's cross-integrity post-message keyboard transport.
• All GUI operations share one process-wide coordinator so multiple MCP clients cannot concurrently mutate the desktop. UI Automation actions are preferred over injected input; screenshots are optional and temporary PNG files are removed after capture.
• Audit records metadata only; it does not record file contents, terminal input/output, Authorization headers, API keys, screenshot pixels, or real process/window IDs. Writes and GUI mutations are serialized within their respective safety domains, and audit logs rotate at 10 MB with four bounded backups.

Security reports should use GitHub Private vulnerability reporting, not a public issue.

User data lives under:

%APPDATA%\DesktopMCP\settings.json
%LOCALAPPDATA%\DesktopMCP\secrets\tunnel-runtime-key.dpapi
%LOCALAPPDATA%\DesktopMCP\logs\audit.jsonl
%LOCALAPPDATA%\DesktopMCP\workspace\

These internal paths intentionally retain DesktopMCP for upgrade compatibility even though the public product name is DeskMCP.

Tray behavior

• Quit Control Panel (Keep Services Running) closes only the UI.
• Quit DeskMCP stops the Gateway and any Tunnel process owned by this Panel, then closes the UI.
• Externally managed Tunnel processes are not killed by DeskMCP.

Uninstall removes program files. Settings, secrets, logs and the default Workspace are kept unless the user explicitly chooses to purge user data.

Developer workflow

End-user requirements and source-development requirements are intentionally separate.

npm.cmd ci --ignore-scripts
npm.cmd test
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\control-panel\wpf\validate.ps1

For local development, control-panel\wpf\launch.cmd builds the Gateway and .NET 10 Control Panel, then starts the current development build.

Build the complete Windows release with:

scripts\build-installer.cmd

The release pipeline performs Gateway build, clean dist generation, self-contained WPF publish, production-only dependency install, third-party license inventory/notices generation, pinned WinApp CLI provenance/architecture checks, stage smoke, 16-tool validation, Single Instance validation, orphan/lock checks, branded Setup compilation, critical-file SHA-256 integrity generation, injected-failure rollback, corrupt/interrupted-install recovery, install → upgrade → runtime → uninstall smoke, and final release metadata generation.

Generated artifacts live under ignored runtime\release\ and should be attached to GitHub Releases instead of committed.

Release verification

A completed release build writes SHA256SUMS.txt and release-manifest.json beside the final installer.

Get-FileHash .\runtime\release\DeskMCP-Setup-<version>.exe -Algorithm SHA256

Compare the result with SHA256SUMS.txt before running an unsigned build.

Code signing policy

DeskMCP has submitted its application to the SignPath Foundation open-source signing program and is awaiting project approval. See CODE_SIGNING_POLICY.md for the signing roles, provenance rules, approval policy, and publisher-pin model.

Pending project approval: Free code signing provided by SignPath.io, certificate by SignPath Foundation. No release is represented as SignPath-signed until it carries a valid signature from the approved signing workflow.

Privacy and network behavior are documented in PRIVACY.md.

Current limitations

• DeskMCP 0.9.2 includes separate native Windows x64 and Windows ARM64 release artifacts. Both architectures pass the full release-stage, install, upgrade, rollback/recovery, runtime, and uninstall validation chain; the Windows artifacts remain unsigned while the SignPath Foundation application is pending.
• A native macOS ARM64 menu-bar client, release stage, and downloadable Developer Preview artifact pass on Apple Silicon CI. The preview is ad-hoc signed and not notarized; a general-user macOS release still requires Developer ID signing and notarization. See macOS Developer Preview.
• Settings now implement the user-controlled safe-update flow through fixed-repository release checks, immutable metadata, local SHA-256/size verification, optional Authenticode publisher verification, one-click Update Now, and post-install version/profile verification. Unsigned releases can use this verified update path after the integrity gates pass; invalid signatures or configured publisher-pin mismatches are blocked. The already-published 0.9.2 client still contains the older hard gate, so the first release carrying this new updater is a one-time manual installer transition; subsequent eligible immutable releases can use the one-click path.
• The open-source Windows Setup may be distributed unsigned; Windows can still show Unknown Publisher / SmartScreen warnings until a release signing identity is configured.
• Some transitive npm dependencies emit deprecation warnings even though the current production npm audit reports zero vulnerabilities.

Roadmap

Current and post-0.9.2 work is tracked publicly with explicit acceptance criteria:

• 🚧 #5 — Fresh Windows user end-to-end validation — still requires a clean-user install/startup/First Run/uninstall pass outside the development account.
• 🚧 #6 — Optional Authenticode signing — SignPath Foundation approval, first signed artifact verification, and production publisher pin remain pending.
• ✅ #7 — Windows ARM64 packaging and validation — target-aware runtime/installer pipeline and native Windows ARM64 full-chain validation pass on both the feature branch and merged main commit; issue closed.
• ✅ #8 — Safe update mechanism — trust validation, verified download, rollback/recovery, profile preservation, failure handling, and manual fallback are implemented; issue closed. Production signing remains tracked by #6.
• ✅ #9 — Desktop Commander cold-start variance — profiled, attributed to upstream initialization variance, surfaced with startup diagnostics, and closed.
• 🚧 #10 — User-controlled updater UI — the one-click verified update path is implemented; production Authenticode remains an optional publisher-identity enhancement tracked separately from basic updater availability.

Support DeskMCP

DeskMCP is free and open-source. If it saves you time and you would like to support ongoing maintenance, you can sponsor the project through GitHub Sponsors once the edmen12 Sponsors profile is approved.

Sponsorship is entirely optional and never changes access to DeskMCP, feature availability, security treatment, or support priority. The repository funding button is configured in .github/FUNDING.yml.

Support

Start with docs/TROUBLESHOOTING.md. For reproducible bugs, feature requests, and private security reporting, see SUPPORT.md. Never post Tunnel runtime keys, API keys, or private file contents in a public issue.

Project files

• SUPPORT.md — support channels and reporting guidance
• SECURITY.md — vulnerability reporting and security boundaries
• PRIVACY.md — local data and user-controlled network behavior
• CODE_SIGNING_POLICY.md — SignPath roles, build provenance, approval and publisher-pin policy
• CONTRIBUTING.md — contribution workflow
• CHANGELOG.md — project changes
• RELEASE_CHECKLIST.md — release QA
• THIRD_PARTY_NOTICES.md — bundled dependency licensing
• docs/USER_GUIDE.md — illustrated installation and usage guide
• docs/COMPUTER_USE.md — Windows Computer Use flow, permissions, observation safety, and backend packaging
• docs/MACOS_DEVELOPER_PREVIEW.md — Apple Silicon Developer Preview download, checksum, and Gatekeeper guidance
• docs/TROUBLESHOOTING.md — common setup and recovery paths
• docs/UPDATE_SECURITY.md — update trust model, execution gates, and rollback/recovery contract
• docs/SIGNPATH_APPLICATION.md — SignPath Foundation application status and post-approval integration plan
• docs/BRAND.md — DeskMCP visual identity and brand rules

License

DeskMCP is licensed under the Apache License 2.0. See LICENSE.

Third-party components retain their own licenses; see THIRD_PARTY_NOTICES.md and the license files bundled with the release.

---

Built as a personal open-source project by edmen12.