Local Commander

Bring your Windows workspace into ChatGPT with a self-hosted MCP server for files and process tools.

· Windows 10 / 11 · Self-hosted · MIT

Why Local Commander · Start with ChatGPT · Keep control · Technical details · 한국어 안내

Why Local Commander?

Connect ChatGPT or local MCP clients to your Windows PC without routing your source code or shell through a third-party SaaS relay.

Related MCP server: Chat On Steroids

Start with ChatGPT

ChatGPT is in active use with the maintainer's current Windows deployment.

Connect ChatGPT to your Windows workspace

ChatGPT uses a fixed HTTPS MCP endpoint. Your Windows PC connects outward through an authenticated relay and handles the file and process tools locally.

For your own installation

Prepare a Windows server, a compatible fixed HTTPS relay, and authentication and pairing for your ChatGPT connection. The current deployment uses a CommanderSocketRelay v1 service with an outbound WebSocket connection from the PC.

This repository includes the WebSocket client (relay-socket-client.mjs / launch-socket.mjs) for that existing relay. The included relay-worker.mjs implements a separate HTTP upstream relay; it does not provide the WebSocket relay service. The setup wizard creates local configuration, but does not deploy a relay or complete ChatGPT authentication.

See Architecture and connection requirements for the components and connection paths.

3 copy-paste prompts to try first

Once your connection is available, test your setup in increasing order of capability:

1. Verify workspace boundaries (read-only)

Use Local Commander to call get_config and list_directory on my configured workspace, then show which folders are readable versus writable.

2. Search and make a SHA-256 guarded edit

Use Local Commander to search for TODO comments in my workspace with start_search, read the matching file with read_file, and update that exact block using edit_block with its current expectedSha256.

3. Run a supervised verification command

Use Local Commander to run "npm test" in my project folder with start_process, inspect the output with read_process_output, and summarize the test results.

The wizard provides templates for Claude Desktop, Cursor, and Codex CLI. Connections and tool execution in these apps have not been verified. These examples use the local STDIO server.

Prepare a new local installation

Requirements: Windows 10 or 11, Git, Node.js 20 or later, and Python 3.11 or later for process supervision and optional login recovery.

git clone https://github.com/shinjaehyun20/local-commander.git
cd local-commander
npm ci --ignore-scripts
npm run setup -- --print-clients

Choose a folder to read. For a first connection, leave write access and shell execution disabled, and choose local deployment mode. The wizard writes config.json and prints the client snippets in your terminal.

The snippets contain the absolute paths for your checkout. Use those generated paths in the examples below, and keep any existing servers in your client configuration. Review an existing config.json before re-running the wizard: it writes a new configuration and does not preserve every previous option.

Claude Desktop · Connection untested

Merge the generated local-commander entry into the mcpServers object in %APPDATA%\Claude\claude_desktop_config.json, then quit and reopen Claude Desktop.

{
  "mcpServers": {
    "local-commander": {
      "command": "node",
      "args": ["C:/path/to/local-commander/server.mjs", "--config", "C:/path/to/local-commander/config.json"]
    }
  }
}

Local MCP server configuration guide

Cursor · Connection untested

Merge the entry into ~/.cursor/mcp.json for your user, or .cursor/mcp.json inside the project. The example below adds an explicit stdio type to the wizard's command and arguments.

{
  "mcpServers": {
    "local-commander": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/path/to/local-commander/server.mjs", "--config", "C:/path/to/local-commander/config.json"]
    }
  }
}

Cursor MCP configuration guide

Codex CLI · Connection untested

Add the generated TOML section to the active Codex configuration, normally ~/.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"]

Codex MCP configuration guide

Check the connection in your chosen app

After the app loads the server, use the read request above and inspect the actual tool response. A generated configuration or a visible server entry alone does not verify a successful tool call.

Start small. Keep control.

Read first. Add editing or process execution when your workflow needs it.

{
  "name": "Local Commander",
  "readRoots": ["D:\\workspace", "C:\\Docs\\Reference"],
  "writeRoots": ["D:\\workspace\\sandbox"],
  "allowShell": false,
  "allowRemoteWrites": false
}

In this configuration, the assistant can inspect files across D:\workspace and C:\Docs\Reference, can only create or modify files inside D:\workspace\sandbox (with expectedSha256 verification on existing files), and cannot spawn shell processes until allowShell is explicitly enabled.

For a closer look

Inspect the implementation, setup options, and current verification results.

System architecture

flowchart LR
  subgraph Clients["AI / MCP Clients"]
    CGPT["ChatGPT (HTTPS MCP)"]
    LOCAL["Local STDIO Clients\n(Claude / Cursor / Codex)"]
  end

  subgraph Edge["Fixed HTTPS Origin / Relay"]
    WSS["CommanderSocketRelay v1\n(/_relay/connect)"]
    WORKER["HTTP Upstream Relay\n(relay-worker.mjs)"]
  end

  subgraph Host["Your Windows 10/11 PC (Local Commander)"]
    OAUTH["OAuth 2.1 + PKCE Gate\n(remote.mjs / vendor-auth)"]
    POLICY["Root & Hash 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"| WSS
  WSS <-->|"Outbound WSS (launch-socket.mjs)"| OAUTH
  WORKER -.->|"Named / Quick Tunnel (launch.mjs)"| OAUTH
  OAUTH --> POLICY
  LOCAL <-->|"Local STDIO"| POLICY
  POLICY --> CORE
  CORE --> JOB

Connection paths

The socket launcher restores the remote server and relay connection without creating a first-time pairing code. The standalone remote entry point and the non-socket launcher create pairing codes. Provisioning a new remote deployment therefore requires a pairing path as well as the relay configuration; the desktop-client snippets do not configure ChatGPT.

Source: server, remote authentication, socket launcher, WebSocket client, HTTP relay Worker, tunnel configuration.

File and process boundaries

• File paths are resolved and checked against readRoots and writeRoots, including resolved symlink or junction targets.

• write_file requires the current expectedSha256 when a file already exists. edit_block requires the hash and exactly one matching text block. These are stale-content checks, not exclusive file locks.

• Process execution runs with the Windows user's permissions. The file-tool roots are not an operating-system sandbox for launched programs. The current configuration has an allowShell switch, not an executable allowlist.

• Windows process supervision uses supervise.py and a Job Object for owned process cleanup. Session tools operate on Commander-owned sessions.

• Remote file changes require allowRemoteWrites, the relevant OAuth scope, and an allowed write root. Remote process creation requires allowRemoteWrites, allowShell, process.execute, and a working directory within a readable root.

• Authentication state uses atomic JSON writes. Corrupt state is preserved as a backup and raises an error instead of being silently reset.

Source: file and process core, process supervision, remote scope checks, state persistence. See SECURITY.md for security reporting.

A first local read configuration

For a new checkout, the non-interactive equivalent of the read-first setup is:

node setup-wizard.mjs --non-interactive --read-root "C:\Projects" --mode local --print-clients

Repeat --read-root for additional folders. Add a --write-root only when you intend to permit file changes in that folder.

The wizard writes config.json, creates missing selected root folders, canonicalizes paths with fs.realpathSync.native, and derives a workspace identity for a new configuration. In relay mode it also creates or reuses a relay secret. It does not start the server, install a login task, provision the external relay, or register a client connection.

Generated files and runtime state

Source: setup wizard, state paths, startup recovery, startup task installer.

Tool catalog

The full server catalog defines 16 tools. The read-only HTTP transport and the remote server with allowRemoteWrites: false expose the 10 read and diagnostic tools. A client controls which server tools it makes available in a conversation; the server catalog alone does not verify client exposure.

See the tool definitions and implementation for exact inputs, limits, and policy checks.

Verification

View current main CI results · Browse test source · Workflow

The repository includes 49 Node.js tests and 11 Python tests covering file and process behavior, tool contracts, OAuth 2.1 + PKCE, atomic state persistence, relay transports, setup wizard canonical path handling, source-manifest integrity, and Windows startup recovery.

On Windows (Node.js 20+ and Python 3.11+):

npm test
py -3.11 tests/startup_test.py

SOURCE_MANIFEST.json records source and test hashes, checked automatically by the manifest test. App-level connections, a newly provisioned external relay, and physical Windows reboot or login cycles require their own host verification.

Local Commander 요약

Local Commander는 Windows 10/11 PC의 로컬 폴더와 프로세스 도구를 ChatGPT(고정 HTTPS/WSS 릴레이 및 OAuth 2.1 + PKCE 연동) 또는 로컬 MCP 클라이언트(STDIO)에 연결하는 100% 셀프호스팅 Windows MCP 서버입니다.

• 외부 SaaS 중계 서버 무의존: 서드파티 유료 클라우드 릴레이에 소스 코드나 셸 권한을 맡기지 않고, 본인 소유의 Windows PC와 직접 제어하는 릴레이/도메인에서 동작합니다.

• 읽기/쓰기 경로 분리 및 해시 검증: readRoots와 writeRoots를 분리 설정하며, 심볼릭 링크·정션 우회를 차단하고 기존 파일 수정 시 expectedSha256 해시 일치를 먼저 확인합니다.

• Windows Job Object 기반 프로세스 감독: supervise.py를 통해 실행된 프로세스와 하위 자식 트리까지 추적·정리합니다.

• 검증 명령어:

  npm ci --ignore-scripts
  npm run setup -- --print-clients
  npm test
  py -3.11 tests/startup_test.py

Source code · MIT License · Third-party notices

Local Commander · A self-hosted Windows MCP server.