🖥️ Desktop Commander MCP

Give ChatGPT a controlled bridge to your Windows computer through the Model Context Protocol (MCP).

Python MCP Transport Platform

Desktop Commander is a Python MCP server for ChatGPT. It exposes tools for local files, folders, processes, Windows automation, a dedicated Chrome browser session, web-page interaction, and API inspection. An ngrok HTTPS tunnel lets ChatGPT connect to the server running on your PC.

✨ Capabilities

Area	What ChatGPT can do
📁 Files & folders	Read, write, copy, move, search, inspect, and organize local files
⚙️ Processes & system	Run commands, manage background sessions, inspect processes, and view system information
🪟 Windows automation	Open apps, capture screenshots, focus windows, type, click, scroll, and use shortcuts
🌐 Chrome control	Open URLs, inspect tabs, navigate, execute JavaScript, and read page content
🧭 Web interaction	Find page elements, fill fields, click elements, and inspect interactive controls
🔌 API inspection	Capture in-page fetch/XHR activity, inspect captured calls, and make API requests

🧱 Architecture

flowchart LR
    C["ChatGPT"] -->|"HTTPS / MCP"| N["ngrok tunnel"]
    N -->|"http://127.0.0.1:8000"| M["Desktop Commander\nFastMCP server"]
    M --> F["Files & folders"]
    M --> W["Windows & processes"]
    M --> B["Dedicated MCP Chrome profile"]

The server uses Streamable HTTP and serves its MCP endpoint at the root path (/). In ChatGPT, enter the ngrok HTTPS URL exactly as shown—do not append /mcp.

🧰 Tech stack

Python 3.13+ — runtime
MCP Python SDK / FastMCP 1.x — MCP server and Streamable HTTP transport
ngrok — public HTTPS tunnel to the local server
Selenium + ChromeDriver — browser control and page automation
PyAutoGUI + PyGetWindow — Windows desktop interaction
psutil + requests — process/system information and API calls

🚀 Quick start

1. Clone the project

git clone https://github.com/kathirm1323-ai/MCP.git
cd MCP

2. Create a Python environment and install dependencies

py -3.13 -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

3. Install and authenticate ngrok

Install ngrok from ngrok.com, sign in, then add the authtoken from your ngrok dashboard:

ngrok config add-authtoken YOUR_NGROK_AUTHTOKEN

4. Start the MCP server

Double-click start_mcp.bat.

The script starts the local MCP server on port 8000, waits for it to boot, and then starts ngrok. Keep the two command windows open while you use the connector.

5. Connect it to ChatGPT

Copy the Forwarding https://... address displayed by ngrok.
In ChatGPT, open Settings → Apps → Create new connector.
Paste the HTTPS address directly. Do not add /mcp.
Choose No authentication and create the connector.
Start a new chat and enable your Desktop Commander connector.

🔁 Typical workflow

Start start_mcp.bat
        ↓
Copy ngrok's HTTPS forwarding URL
        ↓
Create or update the ChatGPT connector
        ↓
Ask ChatGPT to use Desktop Commander
        ↓
ChatGPT calls a tool → ngrok → your local MCP server → result in ChatGPT

Example prompts:

Use Desktop Commander to list files in C:\Users\kathi\Documents.

Use Desktop Commander to open https://github.com in Chrome.

Use Desktop Commander to take a screenshot and tell me which windows are open.

🧩 Tool reference

Category	Tools
File	`read_file`, `read_multiple_files`, `write_file`, `edit_block`, `search_and_replace`, `copy_file`, `get_file_info`
Directory	`list_directory`, `directory_tree`, `create_directory`, `delete_file`, `move_file`
Search	`search_files`
Process	`run_command`, `start_process`, `read_process_output`, `stop_process`, `list_sessions`
System	`list_processes`, `kill_process`, `get_system_info`
Windows	`open_app`, `take_screenshot`, `click_screen`, `type_text`, `scroll_screen`, `move_mouse`, `keyboard_shortcut`, `wait_seconds`, `get_open_windows`, `focus_window`, `get_screen_size`
Chrome	`open_url`, `get_current_tab`, `list_tabs`, `close_tab`, `switch_to_tab`, `reload_tab`, `go_back`, `go_forward`, `execute_javascript`, `get_page_content`
Web scrape	`scrape_element`, `click_element`, `fill_input`, `get_page_elements`
API	`start_api_capture`, `get_captured_apis`, `get_api_detail`, `make_api_call`

🌐 Chrome behavior

Chrome automation uses a dedicated MCP Chrome profile with remote debugging enabled. This avoids disturbing your usual Chrome tabs, windows, or signed-in profile.

The first time you use a Chrome tool, a separate Chrome window may open. Sign in to websites such as GitHub in that MCP-controlled window when needed.

🔗 Permanent ngrok URL (optional)

By default, ngrok creates a temporary HTTPS URL that changes after each restart. To keep a permanent ChatGPT connector URL:

Reserve a domain in the ngrok dashboard.
Open start_mcp.bat.
Set NGROK_DOMAIN to the reserved hostname:

set "NGROK_DOMAIN=your-domain.ngrok-free.app"

The domain must belong to the same ngrok account as your configured authtoken.

📂 Project structure

MCP/
├── server.py            # FastMCP server and tool implementations
├── start_mcp.bat        # Starts the server and ngrok tunnel
├── stop_mcp.bat         # Stops the server and tunnel
├── status_mcp.bat       # Checks server/tunnel status
├── tray_icon.py         # Optional system-tray controller
├── autostart_mcp.bat    # Optional Windows startup launcher
├── run_hidden.vbs       # Optional hidden launcher
├── requirements.txt     # Python dependencies
└── HOW_IT_WORKS.md      # More implementation detail

🔒 Security notes

This server can read and change files, run commands, control apps, and interact with websites on your PC. Treat its ngrok URL like a password.

Connect it only to a ChatGPT account you control.
Do not share the ngrok URL publicly.
Stop the server when you are not using it with stop_mcp.bat.
Review tool requests carefully before approving actions that delete files, run commands, or submit web forms.
The connector is configured with No authentication; the ngrok URL is therefore the access boundary.

🛠️ Troubleshooting

Problem	What to do
ChatGPT says the URL is unsafe	Use the HTTPS ngrok forwarding URL, not `localhost`.
ChatGPT cannot find the server	Confirm `start_mcp.bat` is still running and update the connector with the newest temporary ngrok URL.
`ERR_NGROK_320`	The configured domain belongs to a different ngrok account. Leave `NGROK_DOMAIN` blank or reserve a domain in your own account.
Python points to an old user profile	Delete `venv`, recreate it with `py -3.13 -m venv venv`, then reinstall requirements.
Chrome tools cannot connect	Restart the MCP server. Chrome control opens a separate MCP browser profile automatically.

📄 License

MIT