Secure Local Workspace MCP (secure local workspace MCP)

English | 中文（默认）

A secure local workspace gateway for ChatGPT and Codex. Through MCP it exposes only explicitly authorized project directories and provides restricted file reading, search, patch-based modification, Git checks, and whitelisted task capabilities. It never grants the model arbitrary Shell, deletion, commit, push, or deployment permissions.

Use Cases

• Read, analyze, and modify local project code from the ChatGPT web interface.

• Let Codex access multiple user-authorized projects through a unified MCP toolset.

• Add directory boundaries, file size limits, and SHA-256 concurrency protection to write operations.

• Restrict operations such as tests and builds to a whitelist of tasks defined in the local configuration.

A secure local workspace gateway for ChatGPT and Codex.

Features

The server validates real paths and blocks .., absolute paths, and symlink escapes. Projects are read-only by default; write tools only take effect when a project is configured with writable: true.

This project intentionally does not provide:

• Arbitrary Shell or arbitrary command execution;

• File deletion or overwrite-style creation;

• Git commit, push, or branch rewriting;

• Production deployment or remote server operations.

Directories and Private Data

The repository contains only source code, sample configuration, and automation scripts. Real authorization configurations, API Keys, tunnel configuration, and logs must be kept outside the repository.

Windows recommended directory:

项目源码              <clone-directory>
授权配置              %USERPROFILE%\.secure-local-workspace-mcp\config.json
隧道 profile          %USERPROFILE%\.secure-local-workspace-mcp\tunnel-profiles\
运行时 API Key        用户自选的受保护文件或环境变量
tunnel-client         用户自选的本机工具目录

Legacy %USERPROFILE%\.local-project-workspace\config.json is still automatically read when the new location does not exist, for a seamless upgrade.

Requirements

• Windows, macOS, or Linux; automation scripts are primarily for PowerShell on Windows.

• Node.js 20 or newer.

• Git.

• If connecting to the ChatGPT web client: you must be able to create a Tunnel on OpenAI Platform and use developer mode in ChatGPT.

Full Manual Setup

1. Get the source code and install dependencies

Run:

git clone https://github.com/dxawdc/secure-local-workspace-mcp.git
Set-Location .\secure-local-workspace-mcp
npm ci
npm test
npm run smoke:mcp

2. Create the local authorization configuration

Use the automation script to create your first project configuration:

.\scripts\bootstrap-config.ps1 `
  -ProjectId "my-app" `
  -ProjectLabel "我的应用" `
  -ProjectRoot "D:\Projects\my-app"

The script creates a read-only project by default. To confirm the write risk, explicitly add -Writable:

.\scripts\bootstrap-config.ps1 `
  -ProjectId "my-app" `
  -ProjectLabel "我的应用" `
  -ProjectRoot "D:\Projects\my-app" `
  -Writable `
  -Force

You can also copy config.example.json and save it as:

%USERPROFILE%\.secure-local-workspace-mcp\config.json

An example task whitelist:

{
  "tasks": {
    "test": {
      "command": "npm",
      "args": ["test"],
      "timeoutSeconds": 300
    }
  }
}

ChatGPT or Codex can only submit the task name test; they cannot change the command or arguments.

3. Start and check the MCP server locally

.\scripts\start-local.ps1

or

npm start

The process writes the actual config path and number of authorized projects to stderr. The MCP uses stdio; no HTTP page is available in the foreground.

4. Connect Codex

The repository contains .codex-plugin/plugin.json, .mcp.json, and a companion skill. The personal plugin compatibility ID remains local-project-workspace to avoid breaking existing installations; the display name has been updated to "Secure Local Workspace MCP".

Place the repository in %USERPROFILE%\plugins\local-project-workspace, or create a Junction that points to the cloned directory. Then install or refresh the plugin through the personal marketplace. After updating, start a new Codex task so the MCP server and skills are reloaded.

5. Create an OpenAI secure MCP Tunnel

1. In the OpenAI Platform Tunnel page, create a Tunnel and link it to the target ChatGPT workspace.

2. Create a separate Runtime API Key. Long-running processes should use only the Runtime Key, not the Admin Key.

3. Download the official tunnel-client from OpenAI, verify the SHA-256 checksum from the release page, then extract it.

4. Store the Runtime API Key in a protected file outside the repository, or inject it through an approved secret management tool. Never write it into shell history, sample configuration, or Git.

5. Run the provided script to create and verify the profile.

It is recommended to use an ACL-protected file reference. The following command only passes the file path, not the key content:

.\scripts\setup-tunnel.ps1 `
  -TunnelId "tunnel_REPLACE_ME" `
  -TunnelClient "C:\Tools\tunnel-client\tunnel-client.exe" `
  -ControlPlaneApiKeyRef "file:C:\Secrets\openai-tunnel-runtime-key.txt" `
  -ProfileDir "$env:USERPROFILE\.secure-local-workspace-mcp\tunnel-profiles"

If the computer uses a local proxy to reach OpenAI:

.\scripts\setup-tunnel.ps1 `
  -TunnelId "tunnel_REPLACE_ME" `
  -TunnelClient "C:\Tools\tunnel-client\tunnel-client.exe" `
  -ControlPlaneApiKeyRef "file:C:\Secrets\openai-tunnel-runtime-key.txt" `
  -ProfileDir "$env:USERPROFILE\.secure-local-workspace-mcp\tunnel-profiles" `
  -HttpProxy "http://127.0.0.1:7890"

The script runs tunnel-client init once and runs doctor --explain. When validation succeeds, start the tunnel in the foreground:

& "C:\Tools\tunnel-client\tunnel-client.exe" run `
  --profile secure-local-workspace-mcp `
  --profile-dir "$env:USERPROFILE\.secure-local-workspace-mcp\tunnel-profiles"

6. Create a private plugin in ChatGPT

1. Open ChatGPT settings and enable developer mode.

2. Go to the plugin page and choose "Create an App".

3. Select Tunnel as the connection type, then select the newly created Tunnel or enter the Tunnel ID.

4. This service does not need additional OAuth; choose "No authentication". The Runtime key is used only between the local client and OpenAI control plane.

5. Read the risk notice, then confirm to create the plugin.

6. Verify the 10 required tools are available, then run a read-only test.

Initial verification prompt:

@Secure Local Workspace MCP 调用 list_projects，只返回项目名称和是否可写。

Modification prompt:

@Secure Local Workspace MCP 读取 my-app 的 README.md，先说明修改计划，再用哈希保护补丁修改并展示 git_diff。

Automated Setup

The repository includes three PowerShell scripts:

1. bootstrap-config.ps1 – creates the project authorization config without handling secrets.

2. setup-tunnel.ps1 – generates a Tunnel profile and runs doctor.

3. register-tunnel-startup.ps1 – registers the verified profile as a startup task for the current user.

For complete automation examples, parameter documentation, rollback, and CI/ops notes, see automation configuration reference.

Daily Operation

View local configuration diagnostics

In ChatGPT or Codex, call diagnostics and list_projects. Do not rely on the model to guess project IDs.

Update the repository

git pull --ff-only
npm ci
npm test
npm run smoke:mcp

If MCP tool definitions change, you need to restart the tunnel client and refresh the tools in ChatGPT; Codex may need a new conversation.

Stop the startup task

Stop-ScheduledTask -TaskName "Secure Local Workspace MCP Tunnel"

Remove the startup task

Unregister-ScheduledTask -TaskName "Secure Local Workspace MCP Tunnel" -Confirm:$false

This only removes the startup task; it does not delete the Tunnel, API Key, profile, or project configuration.

Troubleshooting

Tunnel is healthy locally but ChatGPT calls time out

• Check whether api.openai.com:443 requires a proxy.

• The browser using a system proxy does not mean that the Go-based tunnel client will read the same proxy.

• Set http_proxy for the profile, or set HTTPS_PROXY for the launching process.

• Use tunnel-client runtimes status <alias> --json to distinguish between process_running, healthy, ready, and remote query errors.

ChatGPT does not discover tools

• Make sure tunnel-client is actually running.

• Run doctor --explain.

• Confirm that the Tunnel is bound to the current ChatGPT workspace.

• Click "Refresh Connection" or "Refresh Models" in the plugin settings.

• Check the startup log for the correct config path and the number of authorized projects.

Project list is empty

• Does the server use the new or legacy configuration path?

• Also you can set LOCAL_PROJECT_WORKSPACE_CONFIG to point to an explicit config file.

• Verify that the JSON format is correct, the project ID matches, and the directory exists.

Write access is denied

• The project must be set to writable: true.

• For an existing file, re-call read_file to get the latest SHA-256.

• If the file has changed, the previous hash is stale; this is intentional concurrency protection.

Pre-release Security Check

Before publishing, fork, or committing, at least:

• check that no API key, GitHub Tocken, private key or credential is present in the repository;

• there is no real Tunnel, organization, or workspace ID;

• no real config.json, logs, downloaded files, or runtime profiles are committed;

• no personal usernames, absolute paths, or private repository URLs are reference;

• remove node_modules, build artifacts, and temporary files.

The repository .gitignore covers the Common Team-sensitive paths, but does not replace token revocation.

License

MIT