DeskMCP

DeskMCP

DeskMCP is an open-source local-first MCP policy gateway that gives ChatGPT controlled access to local files and terminal sessions. 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	File tools stay inside the folder you explicitly select.
Secure by default	First run starts in Read-only mode; Full Control is 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: 13 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

The Tunnel provides the remote transport. The policy decision still happens locally before a filesystem or process action is forwarded to Desktop Commander.

Permission profiles

• Read — default; read, list, metadata and bounded search only.
• Write — adds guarded create/edit/write/move operations inside the selected Workspace.
• Full — session-only; adds Gateway-owned terminal/process sessions.

Full is never persisted. Restarting DeskMCP returns to the last safe persisted profile: Read or Write.

Tool surface

DeskMCP currently exposes a stable 13-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

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.

Security model

• Gateway HTTP binds only to 127.0.0.1:8765.
• Allowed filesystem access is restricted to the locally selected Workspace.
• Lexical and canonical path checks block symlink/junction escapes.
• Sensitive paths such as .env, .npmrc, .pypirc, .netrc, .ssh, .gnupg, and .aws/credentials are denied by default.
• Search injects sensitive-path exclusions before Desktop Commander/ripgrep reads candidate files.
• Writes use read-before-write observations and reject stale changes; the observation cache is bounded to 1024 entries and eviction never widens write permission.
• Process tools use opaque Gateway-owned session IDs instead of exposing arbitrary Windows PID control; at most 32 owned sessions are retained and new sessions are refused at the cap rather than orphaned.
• Audit records metadata only; it does not record file contents, terminal input/output, Authorization headers, API keys, or real process PIDs. Writes are serialized and 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, self-contained WPF publish, production-only dependency install, third-party license inventory/notices generation, stage smoke, 13-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

• The current public v0.9.1 release is Windows x64. Native Windows ARM64 packaging and full install/upgrade/runtime/uninstall validation now pass on GitHub's Windows ARM64 runner; the first public ARM64 artifact will ship with a future release rather than mutating v0.9.1.
• 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 download, local SHA-256/size verification, WinVerifyTrust, compiled publisher-pin checking, explicit install, and post-install version/profile verification. Current builds keep automatic execution disabled because no production Authenticode publisher pin is compiled in; manual installer upgrades remain available.
• The open-source Windows Setup may be distributed unsigned; Windows can 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

Post-0.9.1 work is tracked publicly with explicit acceptance criteria:

• Fresh Windows user end-to-end validation
• 🚧 #6 — macOS native client and packaging — SwiftUI menu bar, Keychain, Login Item, Darwin ARM64 runtime stage, Apple Silicon CI, and downloadable Developer Preview artifact pass; Developer ID signing/notarization and a stable GitHub Release asset remain
• ✅ #7 — Windows ARM64 packaging and validation — target-aware runtime/installer pipeline and native Windows ARM64 full-chain CI pass; first public ARM64 artifact is deferred to a future release so v0.9.1 stays unchanged
• 🚧 #8 — Safe update mechanism — download/verify/install/post-install security-hold path is implemented; production Authenticode credential, compiled publisher pin, immutable future release and signed end-to-end execution remain
• ✅ #9 — Desktop Commander cold-start variance — profiled, attributed, and surfaced with startup diagnostics

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/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.