Turn ChatGPT Chat into a local coding agent.
MoonDesk is an open-source local MCP server that gives ChatGPT tools to read and edit files, run commands, manage long-running jobs, and control Chromium-based browsers — without using the OpenAI API.
npm install -g moondeskImportant
MoonDesk runs tools on your computer with your user account's permissions. Use a VM or container when you need strong isolation.
MoonDesk lets you use the ChatGPT subscription you already have for local coding work. ChatGPT connects to MoonDesk through a Custom Connector, and MoonDesk exposes your project as a set of MCP tools.
ChatGPT Chat
│
│ Custom Connector
▼
MoonDesk
├─ Files
├─ Shell jobs
├─ Workspaces
└─ Browser / DevTools
No reverse engineering. No API key. No separate agent service.
- Local file tools — read, search, write, edit, and delete inside a workspace.
- Shell commands — run short commands or start background jobs with polling, preserved output, and cancellation.
- Multiple workspaces — serve several projects from one MoonDesk process, each with its own secret MCP URL.
- Browser control — connect ChatGPT to supported Chromium browsers through
chrome-devtools-mcp. - Read-only mode — expose only safe local read tools when mutation is unnecessary.
- Cross-platform — Windows, macOS, and Linux.
- Native binary distribution — install with npm; MoonDesk downloads and verifies the matching release binary on first run.
- Self-update — global npm installs can update and restart from the TUI after confirmation.
Node.js 18 or newer is required.
npm install -g moondeskStart MoonDesk inside the project you want to use:
cd your-project
moondeskChoose:
Control ComputerControl BrowserBoth
On first launch, MoonDesk asks for your ngrok authtoken and static domain. These are stored in ~/.moondesk/config.toml.
Open [w] Workspaces in the TUI and copy the MCP URL for your project.
Each workspace has its own secret URL, for example:
https://your-domain.ngrok-free.dev/<workspace-secret>/mcp
Open ChatGPT's Custom Connector settings and create a connector with:
Name: MoonDesk · <project name>
MCP Server URL: <URL copied from MoonDesk>
Authentication: None
For full coding-agent behavior, allow write actions only when you trust the current workspace and task.
Add this to your ChatGPT custom instructions:
MoonDesk is a coding tool and a custom connector. Always use MoonDesk if the user wants to do anything related to file operations. Always call `moondesk_instruction` after `list_resources`, and follow the instructions it contains.
That's it. Select the MoonDesk connector in a ChatGPT conversation and start working.
One MoonDesk host can serve several project roots at once:
one MoonDesk process
one local server :3200
one ngrok domain
├── Project A -> /<secret-A>/mcp -> D:\ProjectA
├── Project B -> /<secret-B>/mcp -> D:\ProjectB
└── Project C -> /<secret-C>/mcp -> D:\ProjectC
Each workspace keeps its own file boundary, command jobs, retained output, history, and secret connector URL.
Use [w] Workspaces to add, rename, inspect, copy, rotate, or remove projects. Launching moondesk from another project while a host is already running can attach that directory to the existing host instead of starting another server.
Browser control is shared by the host, so workspaces using browser mode control the same selected browser/DevTools bridge.
In multi-tools mode MoonDesk exposes 12 local tools:
| Tool | Purpose |
|---|---|
moondesk_instruction |
MoonDesk usage guidance |
read |
Read workspace files |
search |
Search workspace text |
write |
Create or overwrite files |
edit |
Replace exact text |
delete |
Delete files or directories |
run_command |
Run a short shell command |
start_command |
Start a background command |
list_commands |
List current and retained jobs |
poll_command |
Read incremental job output |
read_command_output |
Read preserved command output |
cancel_command |
Stop a job and its process tree |
Use run_command for short work. Use start_command + poll_command for builds, tests, package installs, dev servers, and other long-running commands.
read-only mode exposes only the local guide/read tools.
Browser mode can add DevTools tools depending on the selected browser and environment.
Dedicated file tools are confined to the selected workspace. MoonDesk rejects path traversal and symlink/junction escapes outside that root.
Shell commands are different. run_command and start_command launch your normal developer shell with the workspace as its working directory. They inherit your normal environment, credentials, PATH, and OS permissions.
The working directory is not an OS sandbox. A shell command can access anything your user account can access.
Use:
read-onlymode when write/shell access is unnecessary;- a VM or container when you need OS-level isolation;
- secret rotation from
[w] Workspacesif a workspace MCP URL is ever exposed.
Caution
Never share a workspace MCP URL. Treat it like a credential.
| Setting | Default / location |
|---|---|
| Config | ~/.moondesk/config.toml |
| Port | 3200 |
| Port override | PORT |
| Initial workspace override | WORKSPACE_ROOT |
| Global instructions | ~/.moondesk/AGENTS.md |
| Codex-compatible instructions | ~/.codex/AGENTS.md |
MoonDesk also checks AGENTS.md in the current workspace. Workspace instructions take priority.
On macOS Terminal.app, MoonDesk can manage a dedicated terminal profile. Set MOONDESK_SKIP_MACOS_TERMINAL_PROFILE=1 to disable that behavior.
| Part | Technology |
|---|---|
| Core | Rust |
| Async runtime / server | Tokio + Axum |
| TUI | Ratatui |
| Tunnel | ngrok |
| MCP server | Custom implementation |
| MCP protocol | 2025-11-25 |
| Browser bridge | chrome-devtools-mcp |
| Distribution | npm + native binaries |
Contributions are welcome. See CONTRIBUTING.md for development setup, required checks, PR rules, and security-sensitive invariants.
Release maintainers should also read docs/RELEASING.md.
ClippyMoon!
MoonDesk is an independent open-source project and is not affiliated with or endorsed by OpenAI. It can execute powerful local actions. Review permissions carefully and use it at your own risk.