# 🖥️ Desktop Commander MCP

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

[![Python](https://img.shields.io/badge/Python-3.13%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/Protocol-MCP-6B4EFF)](https://modelcontextprotocol.io/)
[![Transport](https://img.shields.io/badge/Transport-Streamable%20HTTP-0A7E8C)](https://modelcontextprotocol.io/)
[![Platform](https://img.shields.io/badge/Platform-Windows-0078D4?logo=windows&logoColor=white)](https://www.microsoft.com/windows)

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

```mermaid
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

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

### 2. Create a Python environment and install dependencies

```powershell
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](https://ngrok.com/download), sign in, then add the authtoken from your ngrok dashboard:

```powershell
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

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

## 🔁 Typical workflow

```text
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:

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

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

```text
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:

1. Reserve a domain in the [ngrok dashboard](https://dashboard.ngrok.com/domains).
2. Open `start_mcp.bat`.
3. Set `NGROK_DOMAIN` to the reserved hostname:

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

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

## 📂 Project structure

```text
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