Local Commander
Connects ChatGPT to a self-hosted Windows PC via a fixed HTTPS/WSS relay with OAuth 2.1 + PKCE, letting ChatGPT read and edit files and run supervised processes in configured readRoots/writeRoots on the user's machine.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Zero Third-Party Relay · 100% Self-Hosted Windows MCP Server for ChatGPT & Local AI Clients
🇺🇸 Why Local Commander · 🏗️ Architecture · ⚡ 3-Minute Quickstart · 🛡️ Trust & Sandbox · 🧰 16-Tool Catalog · 🇰🇷 한국어 가이드 (Korean v2.0)
1. Why Local Commander? (First 5-Second Comparison)
Connect ChatGPT Web/App (via your own fixed HTTPS/WSS endpoint) or local desktop MCP clients (stdio) directly to your Windows 10/11 PC without routing your source code, files, or shell outputs through a third-party commercial SaaS relay.
Evaluation Axis | Commercial Hosted Relay SaaS ( | Standard Local | Local Commander ( |
Primary Connection Target | Cloud relay dashboard | Local | ChatGPT-First (Remote HTTPS/WSS + OAuth 2.1 PKCE) AND Local |
Data Sovereignty & Relay Ownership | Commands & outputs traverse third-party vendor cloud servers | Local process only | 100% Self-Hosted Zero Third-Party Relay (runs on your Windows PC + your own domain/Worker) |
Read vs. Write Boundary Separation | Single workspace toggle | Global allowed directory list | Dual Whitelist ( |
Blind-Overwrite Protection & Multi-Session Recovery | Direct file overwrite | Direct file overwrite | Mandatory |
Windows Path & Process Hygiene | Host-dependent | Manual termination; raw temp/virtual paths | Windows Job Object ( |
Verification & Provenance | Closed source | Untracked | 60 Automated Tests (49 Node + 11 Python) + |
Related MCP server: GPT Agent
2. System Architecture
Local Commander separates client transport, authentication & scope enforcement, filesystem/hash policy guards, and Windows Job Object process supervision into auditable layers:
flowchart LR
subgraph Clients["AI / MCP Clients"]
CGPT["ChatGPT Web & App\n(Remote HTTPS MCP)"]
LOCAL["Local STDIO Clients\n(Claude Desktop / Cursor / Codex CLI)"]
end
subgraph Edge["Self-Hosted HTTPS Origin / Relay"]
WSS["CommanderSocketRelay v1\n(/_relay/connect)"]
WORKER["HTTP Upstream Relay\n(relay-worker.mjs)"]
end
subgraph Host["Your Windows 10/11 Workstation (Local Commander)"]
OAUTH["OAuth 2.1 + PKCE Gate\n(remote.mjs / vendor-auth)"]
POLICY["Dual-Root & SHA-256 Policy Gate\n(readRoots / writeRoots / expectedSha256)"]
CORE["16-Tool MCP Engine\n(server.mjs / core.mjs)"]
JOB["Windows Job Object Supervisor\n(supervise.py / startup.py)"]
end
CGPT <-->|"HTTPS /mcp + OAuth 2.1 PKCE"| WSS
WSS <-->|"Outbound WSS (launch-socket.mjs)"| OAUTH
WORKER -.->|"Named / Quick Tunnel (launch.mjs)"| OAUTH
OAUTH -->|"Scopes: desktop.read / write / execute"| POLICY
LOCAL <-->|"Local STDIO"| POLICY
POLICY --> CORE
CORE --> JOB3. 3-Minute Quickstart & First Prompts
Step 1 — Clone & Install (Windows 10/11, Node.js 20+, Python 3.11+)
git clone https://github.com/shinjaehyun20/local-commander.git
cd local-commander
npm ci --ignore-scriptsStep 2 — Run the Setup Wizard & Generate Client Snippets
# Interactive setup wizard (writes config.json and prints client configuration snippets)
npm run setup -- --print-clients
# Or non-interactive read-first setup for a specific project directory:
node setup-wizard.mjs --non-interactive --read-root "D:\workspace" --write-root "D:\workspace\sandbox" --mode local --print-clientsStep 3 — Connect Your AI Client
ChatGPT (Active Maintainer Deployment — Fixed HTTPS/WSS Relay):
Uses outbound WebSocket relay recovery (
node launch.mjs --socket/launch-socket.mjswithrelay-socket-client.mjs) or HTTP upstream tunnel (launch.mjs+relay-worker.mjs) backed byremote.mjsOAuth 2.1 + PKCE (lc_client_,lc_at_,lc_rt_neutral token prefixes).
Claude Desktop / Cursor / Codex CLI (Local
stdioSnippets):Copy the terminal snippet printed by
npm run setup -- --print-clientsinto%APPDATA%\Claude\claude_desktop_config.json,~/.cursor/mcp.json, or~/.codex/config.toml.
Step 4 — 3 Copy-Paste First Prompts to Test Immediately
Once connected, paste these 3 prompts in order to verify read boundaries, surgical SHA-256 diff edits, and supervised process execution:
Prompt 1 — Verify readRoots vs. writeRoots Sandbox Boundaries (Read-Only)
Use Local Commander to call get_config and list_directory on my configured workspace, then show me which folders are read-only (readRoots) versus writable (writeRoots).Prompt 2 — Streaming Search + SHA-256 Guarded Surgical Diff (start_search + edit_block)
Use Local Commander to search for TODO comments in my workspace with start_search, read the matching file with read_file to obtain its current sha256, and update that exact block using edit_block with expectedSha256.Prompt 3 — Run a Supervised Verification Process (start_process + read_process_output)
Use Local Commander to run "npm test" in my project directory with start_process, read the output with read_process_output, and summarize the test results.4. Start Small. Keep Control. (readRoots vs. writeRoots Trust UX)
Worried about an AI agent modifying files outside your target folder or overwriting unsaved local work? Local Commander enforces four deterministic safety gates in core.mjs and remote.mjs:
Dual Directory Whitelist (
readRootsvs.writeRoots): Give the AI broad context across reference repositories inreadRoots, while restricting file creation and edits strictly towriteRoots.Canonical Path & Symlink Escape Prevention: Every path and parent directory is resolved through
fs.realpathSync.native(normalizing Windows 8.3 short paths likeRUNNER~1and blocking symlink/junction traversal outside allowed roots).Optimistic Concurrency (
expectedSha256) & Multi-Session Conflict Recovery:write_file(inrewritemode on existing files) andedit_blockrequire the caller to pass the exactexpectedSha256returned byread_file. If another session modified the file first, the server rejects the stale write and returnsConflict: current SHA256 required (currentSha256=<hash>)for immediate recovery, whilewrite_filewithmode: "append"appends without hash contention.Autonomous Multi-Tab Execution & Explicit Shell/Remote Switches: Both
allowShellandallowRemoteWritesdefault tofalse. When enabled, MCP tool annotations (readOnlyHint: true, destructiveHint: false, openWorldHint: false) prevent multi-tab ChatGPT sessions from stalling on repetitive confirmation modals while enforcing all root, hash, and OAuth scope checks deterministically on the host, supporting up to 16 concurrent supervised process sessions.
{
"name": "Local Commander",
"readRoots": [
"D:\\workspace",
"C:\\Docs\\Architecture-Reference"
],
"writeRoots": [
"D:\\workspace\\sandbox"
],
"allowShell": false,
"allowRemoteWrites": false
}5. 16-Tool Reference Catalog
The MCP engine (server.mjs / core.mjs) exposes 16 tools across 5 categories. When running in read-only HTTP mode (--http) or remote mode with "allowRemoteWrites": false, only the 10 read/diagnostic tools (desktop.read) are exposed.
Category | Tool Name | OAuth Scope | Deterministic Guard & Description |
1. Runtime Config & Diagnostics |
|
| Returns active |
|
| Returns session counters and per-tool invocation statistics. | |
|
| Returns bounded ring-buffer history of recent tool calls for auditability. | |
2. Filesystem Read & Metadata |
|
| Lists entries inside an allowed |
|
| Reads text/UTF-16/UTF-8 files within | |
|
| Batch-reads multiple files within | |
|
| Inspects file size, timestamps, line count, encoding, and | |
3. Streaming Search |
|
| Searches filenames or file contents across |
4. Surgical Diff & File Write |
|
| Replaces an exact unique text block inside |
|
| Creates, rewrites ( | |
|
| Creates a directory hierarchy inside an allowed | |
5. Supervised Process & REPL Control |
|
| Spawns a command inside a Windows Job Object ( |
|
| Sends stdin input to a running Commander-owned interactive REPL or shell session. | |
|
| Reads buffered stdout/stderr and exit state from a Commander-owned process session. | |
|
| Lists active and recently completed Commander-supervised process sessions. | |
|
| Terminates a Commander-owned session and kills its entire child process tree via the Windows Job Object. |
6. Deep Dive: Transports, Setup Flags & Automated Verification
Path | Entry point | Requirements and behavior |
Local STDIO |
| A local client starts the Node process. File access follows the configured roots; |
Local read-only HTTP |
| Binds to |
Remote OAuth server |
| Binds to loopback, serves the OAuth flow and authenticated |
Fixed WebSocket relay |
| Connects outward to an existing compatible CommanderSocketRelay v1 service at |
HTTP upstream relay / named tunnel |
| A separate transport path using |
The socket launcher restores the remote server and relay connection without automatically creating a pairing code. While it is running, node launch.mjs --pair requests a fresh five-minute code in the local state's pairing.json; use it in the existing app's OAuth connection page. Each refresh invalidates the previous code without replacing the stored OAuth clients or tokens. The standalone remote entry point and the non-socket launcher also create pairing codes. Provisioning a new remote deployment still requires the relay configuration; the desktop-client snippets do not configure ChatGPT.
Source: server, remote authentication, socket launcher, WebSocket client, HTTP relay Worker, tunnel configuration.
Setup wizard CLI options (setup-wizard.mjs)
Option | Purpose |
| Choose the output configuration file. Defaults to |
| Add a readable folder. Repeat for multiple folders. |
| Add a writable folder within a readable root. The default list is empty. |
| Enable process creation. Disabled by default. |
| Allow the remote catalog to expose file mutation and process tools. Disabled by default; OAuth scopes and core policy still apply. |
| Select the Python executable for supervision. |
| Select local configuration, a quick tunnel, or fixed WebSocket relay configuration. Relay mode also needs |
| Generate optional |
| Print the Claude Desktop / Cursor JSON and Codex CLI TOML examples. Interactive setup also prints them. |
Generated files and Windows runtime state
File or location | When it is used |
| Written by the setup wizard. Review it before connecting a client. |
| Written only when optional startup configuration is selected. |
Terminal output | Contains desktop-client snippets printed by |
| Default Windows runtime state directory; |
| Persisted OAuth registration and token records (atomic temp-file swap + |
| Service identity and connection state recorded by launchers. |
| One-time pairing information written by pairing-capable entry points. |
| Local shared-secret file created or reused by relay setup. |
Local STDIO Client Templates (Claude Desktop / Cursor / Codex CLI)
Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json)
{
"mcpServers": {
"local-commander": {
"command": "node",
"args": ["C:/path/to/local-commander/server.mjs", "--config", "C:/path/to/local-commander/config.json"]
}
}
}Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"local-commander": {
"type": "stdio",
"command": "node",
"args": ["C:/path/to/local-commander/server.mjs", "--config", "C:/path/to/local-commander/config.json"]
}
}
}Codex CLI (~/.codex/config.toml)
[mcp_servers.local-commander]
command = "node"
args = ["C:/path/to/local-commander/server.mjs", "--config", "C:/path/to/local-commander/config.json"]View current main CI results · Browse test source · Workflow · Status & Release Audit
The repository runs 49 Node.js tests and 11 Python tests on every push to main on windows-latest:
npm test
py -3.11 tests/startup_test.pyNode.js Suite (
npm test→node --test, 49 tests): File/process boundaries, symlink & junction escape blocking,expectedSha256optimistic concurrency, UTF-16LE/BE & CRLF preservation, OAuth 2.1 + PKCE token lifecycle, corrupt auth state backup, WebSocket & HTTP relay clients, setup wizard 8.3 short-path canonicalization (fs.realpathSync.native), andSOURCE_MANIFEST.jsoncryptographic hash verification.Python Suite (
py -3.11 tests/startup_test.py, 11 tests): Windows Job Object child-tree termination (supervise.py), mutex lock (Local\LocalCommanderRecovery-), and login recovery (startup.py).
7. 🇰🇷 한국어 가이드 (Korean v2.0 Overview)
왜 Local Commander인가? (제3자 클라우드 중계 없는 100% 자체 호스팅 Windows MCP)
Local Commander는 Windows 10/11 워크스테이션의 로컬 파일시스템·검색·프로세스 제어 도구를 ChatGPT 웹/앱(고정 HTTPS/WSS 릴레이 및 OAuth 2.1 + PKCE 인증)과 로컬 MCP 클라이언트(Claude Desktop, Cursor, Codex CLI 등 stdio)에 직접 연결하는 100% 셀프호스팅 오픈소스 MCP 서버입니다.
비교 항목 | 상용 클라우드 중계 SaaS ( | 일반 로컬 | Local Commander ( |
ChatGPT 웹/앱 연결 | 유료 클라우드 구독 필요 | 로컬 앱( | ChatGPT-First 고정 HTTPS/WSS 릴레이 + OAuth 2.1 PKCE 기본 내장 |
데이터 주권 및 프라이버시 | 모든 명령어와 파일 출력이 외부 벤더 서버를 경유 | 로컬 프로세스 한정 | 제3자 중계 서버 Zero — 100% 본인 PC 및 자체 도메인/Worker에서 직접 구동 |
읽기/쓰기 권한 분리 | 단일 워크스페이스 허용 | 전역 허용 폴더 목록 |
|
파일 덮어쓰기 방지 및 다중 세션 복구 | 무조건 덮어쓰기 | 무조건 덮어쓰기 | 기존 파일 |
Windows 프로세스/경로 복구 | 호스트 의존 | 수동 종료 필요 | Windows Job Object( |
3분 설치 및 첫 실행 프롬프트 3선
# 1. 저장소 클론 및 의존성 설치
git clone https://github.com/shinjaehyun20/local-commander.git
cd local-commander
npm ci --ignore-scripts
# 2. 대화형 셋업 마법사 실행 (config.json 생성 및 클라이언트 연결 스니펫 출력)
npm run setup -- --print-clients
# 3. 전체 자동화 테스트 스위트 검증 (Node 49개 + Python 11개 = 총 60개 테스트)
npm test
py -3.11 tests/startup_test.py연결 완료 후 ChatGPT(또는 로컬 MCP 클라이언트)에 아래 3가지 프롬프트를 순서대로 붙여넣어 즉시 테스트해 보세요:
권한 경계 확인 (읽기 전용)
Local Commander의 get_config와 list_directory 도구를 호출해서 현재 연결된 워크스페이스의 읽기 허용 폴더(readRoots)와 쓰기 허용 폴더(writeRoots) 설정을 표로 정리해 줘.코드 검색 및 SHA-256 해시 기반 정밀 블록 수정
Local Commander의 start_search로 프로젝트 내 TODO 주석을 검색한 뒤, read_file로 해당 파일의 현재 sha256 해시를 확인하고 edit_block(expectedSha256 포함)으로 안전하게 수정해 줘.Windows Job Object 감독 기반 테스트 실행
Local Commander의 start_process로 프로젝트 폴더에서 "npm test"를 실행하고, read_process_output으로 실행 결과를 읽어 통과 여부를 요약해 줘.
Source code · Status & CI Audit · Security Policy · MIT License · Third-party notices
Local Commander · Built for developers who want ChatGPT & MCP power on Windows without surrendering local data sovereignty.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables ChatGPT to access approved local Windows folders, run commands, control the desktop, and manage session history through a permission-bounded MCP server.5,194MIT
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT on Windows to securely access codebases, Git, terminals, language servers, debuggers, SQLite, local HTTP services, adaptive project memory, engineering skills, checkpoints, audit logs, and sandboxed command execution through MCP tools.MIT
- AlicenseNot gradedqualityBmaintenanceEnables ChatGPT to securely access local files, shell commands, processes, Skills, and external MCP servers through a controlled local bridge with lock/unlock permissions and a Windows desktop control center.10 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables ChatGPT to privately read and edit files, run PowerShell/Git Bash commands, and maintain persistent interactive terminals on a Windows host through authenticated remote MCP.3MIT