desktop-control-mcp
Provides tools for controlling Google Chrome: listing, opening, closing, and focusing tabs, scrolling the active page, and opening Chrome windows under a specific profile.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@desktop-control-mcp open my Documents folder and list what's in it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
desktop-control-mcp
An MCP server that lets an MCP client (Claude Code, Claude Desktop, or claude.ai via a custom connector) open and close applications, files, and folders on this Windows machine.
Tools exposed:
Tool | Does |
| Launch an app by friendly name ( |
| Force-close a running app by name |
| List processes that currently have a visible window |
| Open a file/folder path, or a friendly folder name ( |
| Close any open File Explorer window(s) showing a given folder |
| List the files/subfolders directly inside a folder (name, type, path, size) |
| Open a file/folder with a SPECIFIC app (e.g. a folder in VS Code) - |
| Recursively find duplicate files by content (name, all locations, count, wasted space) |
| List every open File Explorer folder window (path, title, hwnd) |
| Close every open File Explorer folder window |
| Bring an open folder window to front (un-minimizes if needed) |
| Minimize an open folder window |
| List every open Chrome tab (index + title) |
| Open a new Chrome tab, optionally to a URL |
| Close the open tab matching a title search |
| Switch to the open tab matching a title search |
| Maximize Chrome and scroll the active page up/down (simulated PageUp/PageDown) |
| List configured Chrome profiles (name + directory) |
| Open a new Chrome window under a specific profile (most reliable when Chrome isn't already running) |
| Bring an app's window to front / switch to it (un-minimizes if needed) |
| Maximize an app's window |
| Minimize an app's window |
| Report OS, CPU, RAM (total/used/free/%), and disk usage per drive |
| Send Ctrl+Shift+Win+B to restart the graphics driver - fixes a frozen/stuck/black/glitched screen without closing apps or losing work |
| Schedule a full shutdown after a delay. Requires |
| Schedule a restart after a delay. Requires |
| Abort a pending |
Known app aliases live in src/appMap.js — add more there as needed. Any
other name is tried as a literal .exe.
open_path_with's app field is required on purpose: if a request doesn't say which app
to use, the calling model should ask you rather than guess — making the field required
enforces that at the schema level instead of relying on prompt wording. Use plain
open_path for "just open it with whatever's default" requests.
focus_app / maximize_app / minimize_app take an optional pid. If more than one
window of the requested app is open, they refuse to guess — the error lists each
candidate's PID and window title so you (or Claude) can retry with the right pid.
find_duplicate_files matches by content (SHA-256), not filename — two files named
differently but byte-identical count as duplicates; two files with the same name but
different content don't. It groups by file size first and only hashes within a group
that has more than one file, so a folder with mostly unique-sized files is fast. It stops
after 20000 files on a very large tree and sets truncated: true rather than hanging.
Chrome tabs
close_chrome_tab / focus_chrome_tab match by a case-insensitive substring against tab
titles (not URLs) and take an optional index the same way the window tools take pid -
if the query matches more than one tab, they list the candidates instead of guessing.
Built on Chrome's own UI Automation tree (the same mechanism screen readers use), not
taskkill/Win32 windows, since individual tabs aren't OS-level windows at all.
Two things worth knowing:
Only the first Chrome window is used if you have more than one open — tabs in a second Chrome window aren't visible to these tools.
The first Chrome tab call after Chrome starts (or after it's been idle a while) can return an empty list while Chrome's accessibility tree activates. If you get
[]fromlist_chrome_tabswhen you know tabs are open, just call it again.
⚠️ Security model — read before exposing this to the internet
This server can launch and kill processes on your laptop. Anyone who can send it a request has meaningful control of your machine. It is not a toy:
The HTTP transport (
src/http.js) refuses to start withoutMCP_AUTH_TOKENset and requiresAuthorization: Bearer <token>on every request. There is no bypass for this — don't add one.It binds to
127.0.0.1only, never0.0.0.0. The only way it becomes reachable from outside this machine is if you deliberately point ngrok (or something else) at it.Every request is logged to stdout with timestamp and source IP, including rejected (unauthenticated) ones — keep an eye on that console while a tunnel is open.
A small denylist (
PROCESS_DENYLISTin src/appMap.js) blocks closing core OS processes (lsass.exe,winlogon.exe,services.exe, ...) so a bad request can't easily crash the whole session.All dynamic input (app names, paths) is passed to child processes via environment variables, never string-concatenated into a shell/PowerShell command line — this is what prevents a crafted tool argument from smuggling in extra commands.
shutdown_pc / restart_pc — the two tools that can strand you
These are the most destructive tools in this server, so they have three independent safety nets:
confirm: trueis required. Omit it and the tool refuses before touchingshutdown.exe— a guard against an accidental or ambiguous call.A countdown delay (default 60s, min 15s, max 3600s) before anything happens.
cancel_shutdownaborts a pending shutdown/restart during that countdown.
Two things worth knowing that aren't obvious from the tool names:
Unsaved work is not protected. Windows'
shutdown.exeautomatically implies force-close (/f) whenever the delay is greater than 0 seconds — every default call here has a delay, so once the countdown reaches zero, open apps are closed without a save prompt. The delay is your only window to react, not a "Windows will ask first" safety net.restart_pccurrently ends remote control, same asshutdown_pc. This server doesn't auto-start on boot, so after either one fires you'll need to be physically at the machine to get remote control back (auto-start-on-login is a possible follow-up, not set up here).
If you ever need to cancel by hand instead of through an MCP tool call, run shutdown /a
from a normal cmd.exe or PowerShell window — not Git Bash. Git Bash's path
auto-conversion rewrites leading-slash flags like /a into a bogus Windows path before
shutdown.exe ever sees it, so the command silently does nothing (prints usage/help,
exit code 1) instead of cancelling. This bit us during testing of this feature.
What this does not do: there is no arbitrary shell-command tool here on purpose.
"Open/close apps and files" is a large enough attack surface already; a generic
run_command tool would turn this into an unrestricted remote shell. If you extend this
server, keep that boundary in mind.
Practical rules for running this safely:
Treat
MCP_AUTH_TOKENlike a root password. Generate a long random one (see.env.example), never commit it, never post the ngrok URL anywhere public.Only run the tunnel while you're actively using it. Stop
ngrok(and the server, if you want to be extra safe) when you're done for the day.Prefer ngrok's own auth on top of yours.
ngrok http 3939 --oauth=google --oauth-allow-email=you@example.com(requires a paid ngrok plan) or at leastngrok http 3939 --basic-auth "user:longpassword"adds a second lock on the door.Watch the console. Every open/close call this server executes is printed. If you see activity you didn't trigger, kill the ngrok tunnel immediately (Ctrl+C) and rotate
MCP_AUTH_TOKEN.A free ngrok URL changes every time you restart the tunnel — that's a feature, not a bug, since a stale forgotten URL still needs your (rotatable) token to do anything.
Try
shutdown_pc/restart_pclocally over stdio first, with a generousdelaySecondsandcancel_shutdownready to go, before ever calling them through the ngrok tunnel where a dropped connection could keep you from cancelling in time.
Related MCP server: win-rdp-mcp
Setup
npm install
copy .env.example .envEdit .env and set MCP_AUTH_TOKEN to a long random value:
node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"Running locally (stdio) — for Claude Code / Claude Desktop on this machine
No token needed for stdio; the client launches the process directly, so there's no network exposure.
Claude Code:
claude mcp add desktop-control -- node "C:\Users\Al-Fateh\Documents\agentic-system\desktop-control-mcp\src\stdio.js"Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"desktop-control": {
"command": "node",
"args": ["C:\\Users\\Al-Fateh\\Documents\\agentic-system\\desktop-control-mcp\\src\\stdio.js"]
}
}
}Running remotely (HTTP + ngrok) — for claude.ai custom connectors
Start the server:
npm run start:httpIt listens on
http://127.0.0.1:3939/mcpand will refuse to start ifMCP_AUTH_TOKENisn't set.In a separate terminal, tunnel it:
ngrok http 3939Note the
https://<random>.ngrok-free.appURL ngrok prints.Connect a client to
https://<random>.ngrok-free.app/mcpwith headerAuthorization: Bearer <your MCP_AUTH_TOKEN>:Claude Code:
claude mcp add --transport http desktop-control https://<random>.ngrok-free.app/mcp --header "Authorization: Bearer <token>"claude.ai (Settings → Connectors → Add custom connector): paste the URL. If the UI doesn't offer a header field for your account type, you'll need OAuth-based auth instead of a static bearer token to use claude.ai's hosted connector flow — the bearer-token approach above is guaranteed to work with Claude Code today.
When you're done,
Ctrl+Cboth the ngrok tunnel and the server.
Files
src/appMap.js friendly-name -> exe/process map, and the process denylist
src/winControl.js the actual open/close logic (PowerShell + taskkill, injection-safe)
src/server.js MCP tool definitions, shared by both transports
src/stdio.js entry point for local stdio transport
src/http.js entry point for remote HTTP transport (auth required)Available Tools
27 toolscancel_shutdownCancel pending shutdown/restartA
Abort a shutdown_pc or restart_pc that is still in its countdown.
Inputs: no named parameters.
close_all_folder_windowsClose all folder windowsA
Close every currently open File Explorer folder window.
Inputs: no named parameters.
close_appClose applicationA
Force-close a running application by name. Known friendly names: chrome, google_chrome, edge, msedge, firefox, word, winword, excel, powerpoint, outlook, notepad, explorer, file_explorer, calculator, calc, paint, cmd, command_prompt, powershell, vscode, vs_code, spotify, task_manager. Critical system processes are refused.
Inputs: app (required).
close_chrome_tabClose Chrome tabA
Close the open Chrome tab whose title matches the given text (case-insensitive substring match).
Inputs: query (required), index.
close_folder_windowClose folder windowA
Close any open File Explorer window(s) currently showing the given folder path.
Inputs: path (required).
find_duplicate_filesFind duplicate filesA
Recursively scan a folder for duplicate files (same content, by hash - not just same name) and report each duplicate group's file name, every location, and the count, plus total wasted disk space. Stops after 20000 files scanned on a very large tree and reports truncated: true if it hit that cap.
Inputs: path (required).
focus_appBring app window to frontA
Show and switch focus to an app's window (un-minimizes it if needed).
Inputs: app (required), pid.
focus_chrome_tabSwitch to Chrome tabA
Search open Chrome tabs by title and switch to the matching one, bringing Chrome to the front.
Inputs: query (required), index.
focus_folder_windowBring folder window to frontA
Show and switch focus to an open File Explorer window for the given folder (un-minimizes if needed).
Inputs: path (required), hwnd.
list_chrome_profilesList Chrome profilesA
List Chrome browser profiles configured on this machine (name + directory, marks which was last active).
Inputs: no named parameters.
list_chrome_tabsList Chrome tabsA
List every open tab in Chrome (index + title). Operates on the first Chrome window if more than one is open.
Inputs: no named parameters.
list_folder_contentsList folder contentsA
List the files and subfolders directly inside a folder (name, type, path, file size). Accepts a path or a friendly folder name like "documents".
Inputs: path (required).
list_open_foldersList open folder windowsA
List every currently open File Explorer folder window (path, title, hwnd).
Inputs: no named parameters.
list_running_appsList running applicationsA
List currently running applications that have a visible window.
Inputs: no named parameters.
maximize_appMaximize app windowA
Maximize an app's window and bring it to front.
Inputs: app (required), pid.
minimize_appMinimize app windowC
Minimize an app's window.
Inputs: app (required), pid.
minimize_folder_windowMinimize folder windowA
Minimize an open File Explorer window for the given folder.
Inputs: path (required), hwnd.
open_appOpen applicationA
Launch an application on the laptop. Known friendly names: chrome, google_chrome, edge, msedge, firefox, word, winword, excel, powerpoint, outlook, notepad, explorer, file_explorer, calculator, calc, paint, cmd, command_prompt, powershell, vscode, vs_code, spotify, task_manager. Any other value is tried as a literal .exe name.
Inputs: app (required), target.
open_chrome_profileOpen Chrome profileA
Open a new Chrome window under a specific profile. Matches by profile name (e.g. "Work") or exact directory (e.g. "Profile 1") - use list_chrome_profiles to see what's available. Reliable when Chrome is not already running; if Chrome is already open, it verifies whether a genuinely new profile-bound window appeared and returns an error (rather than a false success) if Chrome just opened another window in the profile that was already active.
Inputs: profile (required).
open_chrome_tabOpen new Chrome tabA
Open a new Chrome tab, optionally navigating to a URL.
Inputs: url.
open_pathOpen file or folderA
Open a file or folder using the default Windows handler (Explorer for folders). Also accepts friendly names for standard folders: documents, desktop, downloads, pictures, music, videos, home.
Inputs: path (required).
open_path_withOpen file/folder with a specific appA
Open a file or folder using a SPECIFIC application (e.g. open a folder in VS Code, or a file in Chrome), instead of the OS default handler. Both path and app are required - if the user did not say which app to use, ask them before calling this tool rather than guessing. Use open_path instead if no specific app was requested.
Inputs: app (required), path (required).
restart_graphics_driverRestart graphics driverA
Fixes a frozen, stuck, black, or glitched screen WITHOUT closing apps or losing work. Sends the built-in Windows hotkey Ctrl+Shift+Win+B, which tells the graphics driver to reinitialize. Call this whenever the user says their system/screen is frozen, stuck, unresponsive, or visually glitching and a graphics reset is a reasonable first thing to try. The screen will flicker or go black for a couple of seconds - that is expected.
Inputs: no named parameters.
restart_pcRestart PCA
Schedule a restart of this machine. This server does NOT auto-start after reboot, so remote control ends the same way it would with shutdown_pc until someone starts it again locally. Requires confirm: true.
Inputs: confirm (required), message, delaySeconds.
scroll_chrome_pageScroll Chrome pageA
Scroll the active page in the first Chrome window up or down by simulating PageUp/PageDown key presses.
Inputs: direction (required), amount.
shutdown_pcShut down PCA
Schedule a full shutdown of this machine. Ends ALL remote control until someone is physically at the machine to turn it back on. Requires confirm: true.
Inputs: confirm (required), message, delaySeconds.
system_infoSystem infoA
Report this machine's OS, CPU, RAM (total/used/free/%), and disk usage per drive.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Each tool targets a distinct resource-action pair: app launching/windowing, folder paths/windows, Chrome profiles/tabs, and system control are clearly separated. Even the three 'open' tools differ by target type (app name, default handler, specific app), and close/focus/minimize variants are unambiguous.
Nearly all tools follow a verb_noun snake_case pattern (list_*, open_*, close_*, focus_*, minimize_*), with only system_info and open_path_with as minor deviations. The naming is highly predictable and makes the tool set easy to navigate.
At 27 tools, this is on the heavy side, but the broad desktop-control scope justifies the count: app management, folder windows, Chrome control, and system power actions are all represented. A few niche tools (scroll_chrome_page, restart_graphics_driver) could be considered optional, making it feel slightly bloated.
The tool set covers the major desktop workflows: app launch/focus/window-state, folder browsing and window management, Chrome tab/profile control, and system shutdown/restart. Minor gaps exist—no maximize folder window, no way to pass command-line args to open_app—but nothing blocks the core use cases.
Maintenance
Related MCP Connectors
Control your authorized Windows computers via OAuth: files, shell, apps, and task status.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Run and manage H Company's Computer-Use Agents from any MCP client.
Remote MCP access to authorized Mac and Windows computers, with consent and STOP controls.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to seamlessly integrate with the Windows operating system, performing tasks such as file navigation, application control, UI interaction, and QA testing via the MCP protocol.-
- AlicenseNot gradedqualityBmaintenanceEnables remote control of a Windows desktop via MCP, including screenshots, mouse and keyboard, window management, PowerShell, files, services, registry, scheduled tasks, event log, and network checks.638 npm4GPL 3.0
- AlicenseAqualityCmaintenanceEnables general-purpose Windows desktop automation via MCP tools: opening applications and URLs, taking screenshots, checking whether processes are running, and waiting.6MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to control and interact with a local Windows computer through authenticated MCP tools, including file operations, shell commands, process management, HTTP requests, and system/media inspection.-