ChatGPT Local Agent

Project status 🧭

This is a personal, full-power local MCP system for Windows.

It is usable, but it is DIY. It is not an OS sandbox and it is not a hosted service.

The server runs with the permissions of the Windows account that starts it. If that account can read a file, launch a command, see a browser session, or interact with the desktop, the exposed tools may be able to reach the same surface.

Keep that model in mind while configuring workspaces, browser profiles, scopes, and tunnels.

Architecture 🏗️

Core pieces:

• Streamable HTTP MCP server
• Express HTTP server
• GitHub OAuth identity flow
• local MCP authorization code and access token flow
• scoped MCP tools
• operation journal
• local web dashboard
• PowerShell installer
• fallback PowerShell dashboard
• optional Cloudflare Tunnel exposure

Runtime defaults:

Server:     http://127.0.0.1:8789
MCP:        http://127.0.0.1:8789/mcp
Dashboard: http://127.0.0.1:8789/dashboard

Normal install root:

%LOCALAPPDATA%\chatgpt-local-agent-mcp

Tool surface 🧰

The server registers tools across these categories:

• workspace information
• filesystem read, write, patch, copy, move, delete, search, hash, tree, stat
• Git status, diff, commit
• process start, stop, kill, port list, log tail, wait for port
• shell execution
• browser sessions, navigation, snapshots, console, network, screenshots, CDP attach
• screen, OCR hook, and window listing
• desktop mouse and keyboard automation

Tool access is controlled by MCP scopes:

mcp:read
mcp:write
mcp:shell
mcp:git
mcp:patch
mcp:delete
mcp:process
mcp:screen
mcp:desktop
mcp:browser

Use narrow scopes when possible. Add power only when you need it.

Configuration ⚙️

Create a private .env from .env.example.

Full-power local defaults from .env.example:

GPT_FS_MCP_HOST=127.0.0.1
GPT_FS_MCP_PORT=8789
GPT_FS_MCP_MAX_POLICY_MODE=destructive
GPT_FS_MCP_ENFORCE_WORKSPACE_PROFILES=true
GPT_FS_MCP_SHELL_POLICY=full
GPT_FS_MCP_PROCESS_POLICY=full
AUTH_REQUIRED=true
NODE_ENV=development

For local-only smoke testing before OAuth is configured, AUTH_REQUIRED=false is allowed only while the server is bound to localhost and no tunnel is enabled.

Safe local-only smoke test values:

PUBLIC_BASE_URL=http://127.0.0.1:8789
CLOUDFLARE_TUNNEL_ENABLED=false
AUTH_REQUIRED=false

Never use AUTH_REQUIRED=false with a public URL, public hostname, or tunnel. The installer/server guard against unsafe combinations, but configuration still matters.

For a safer first workspace, define GPT_FS_MCP_WORKSPACE_PROFILES_JSON for one test folder, keep auth enabled for remote use, and guard command execution:

GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded

Use full command policies only when you deliberately want shell and process tools to reach outside declared workspace paths.

For a public or tunneled connector:

AUTH_REQUIRED=true
CLOUDFLARE_TUNNEL_ENABLED=true
PUBLIC_BASE_URL=https://your-public-host.example
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
ALLOWED_GITHUB_LOGINS=your-github-login
OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
OAUTH_REDIRECT_URIS=

Treat .env as security-critical.

OAuth model 🔐

There are two OAuth layers.

GitHub OAuth App → MCP server

You sign in with GitHub.

The server redirects to GitHub, receives the callback, checks the allowed GitHub login, and then issues a local MCP authorization code.

GitHub callback:

https://your-public-host.example/callback

Relevant config:

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
ALLOWED_GITHUB_LOGINS=

ChatGPT connector → MCP server

ChatGPT is the OAuth client talking to this MCP server.

Relevant config:

OAUTH_CLIENT_ID=
OAUTH_CLIENT_SECRET=
OAUTH_REDIRECT_URIS=

The server exposes OAuth metadata at:

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server

The server does not expose dynamic client registration.

Cloudflare Tunnel model 🌐

The intended remote exposure model is:

ChatGPT
  -> https://mcp.your-domain.example/mcp
  -> Cloudflare Tunnel
  -> http://127.0.0.1:8789
  -> local MCP server

No Cloudflare Worker is required for the normal setup.

For a locally managed Cloudflare Tunnel, the dashboard route is read from the local cloudflared configuration file. A minimal route looks like:

ingress:
  - hostname: mcp.your-domain.example
    service: http://127.0.0.1:8789
  - service: http_status:404

The matching .env values are:

PUBLIC_BASE_URL=https://mcp.your-domain.example
CLOUDFLARE_TUNNEL_ENABLED=true
CLOUDFLARED_CONFIG=C:\Users\you\.cloudflared\config.yml

If Cloudflare shows the DNS record as a Tunnel but the tunnel status is Down with 0 active replicas, the dashboard configuration can still be correct. It means the local cloudflared connector is not currently connected.

Security boundaries 🧱

This system is designed to be capable, not sandboxed.

Boundaries it does provide:

• OAuth controls who can connect.
• GitHub login allowlisting controls who can complete auth.
• MCP scopes control tool categories.
• policy modes limit which tools are available.
• workspace profiles can restrict filesystem paths.
• command policies can restrict shell/process behavior.
• journals and logs redact common secret-looking fields.

Boundaries it does not provide:

• It is not an OS sandbox.
• Browser CDP attach can interact with existing browser profiles and logged-in sessions.
• Desktop tools can move the mouse and press keys.
• Shell and process tools run with the local server process permissions.
• An authorized assistant may still read or reveal accessible local secrets if you expose them through files, browser state, desktop, or shell.

For stricter command behavior:

GPT_FS_MCP_SHELL_POLICY=workspace_guarded
GPT_FS_MCP_PROCESS_POLICY=workspace_guarded

workspace_guarded checks the command working directory plus explicit path references and expected touched paths.

It is still not a sandbox.

Workspace profiles 📁

By default, when GPT_FS_MCP_WORKSPACE_PROFILES_JSON is empty, the server creates one workspace profile per detected filesystem root.

On Windows, that means available drive roots such as:

C:\
D:\

That is intentional full-machine access.

GPT_FS_MCP_DEFAULT_CWD only controls the starting directory for relative paths and commands. If it is empty, it falls back to the user Documents\GitHub folder. It does not limit filesystem access by itself.

Custom workspace profiles can be provided with:

GPT_FS_MCP_WORKSPACE_PROFILES_JSON=

Profiles define:

• root path
• allowed policy modes
• backup policy
• secret deny globs

Use profiles to keep the assistant inside the intended workspace instead of exposing more of the machine than necessary.

Browser, screen, and desktop notes 🌐

Browser automation uses Playwright.

If browser binaries are missing after dependency install, run:

npx playwright install

Browser and desktop tools are high-risk because they can interact with visible UI and active sessions.

Use a dedicated browser profile when possible.

Do not attach the server to accounts, profiles, or desktop sessions you are not willing to expose to the connected assistant.

Development 🧪

Install dependencies:

npm ci

Type-check:

npm run type-check

Build:

npm run build

Run tests:

npm test

Run the built server:

npm start

Run in watch mode:

npm run dev

Publish-safe check 🧼

Before sharing the source folder:

npm run audit:publish-safe

The source repo should not include:

• .env
• data/
• node_modules/
• dist/
• *.log
• runtime screenshots
• browser artifacts
• journals
• backups

The included .gitignore excludes the main repo-root runtime directories and logs. Run the publish-safe audit before publishing; it is the final check, not the ignore file alone.

Troubleshooting 🩺

Save .env asks for OAuth values during first local test

If AUTH_REQUIRED=true, OAuth values are required.

For localhost-only smoke checks before OAuth is configured, use:

PUBLIC_BASE_URL=http://127.0.0.1:8789
CLOUDFLARE_TUNNEL_ENABLED=false
AUTH_REQUIRED=false

Do not use this configuration with a public URL or tunnel.

/mcp returns 401

That is normal without a token.

A protected MCP endpoint should reject unauthenticated requests.

/authorize returns invalid_request

Usually one of these does not match the ChatGPT connector request:

• OAUTH_CLIENT_ID
• OAUTH_REDIRECT_URIS
• PUBLIC_BASE_URL
• requested resource
• PKCE settings

/callback works but /token returns 401

The ChatGPT connector secret does not match:

OAUTH_CLIENT_SECRET=

or ChatGPT is not sending the expected client credentials.

GitHub login succeeds but ChatGPT does not connect

Keep the two OAuth layers separate:

GitHub callback:

https://your-public-host.example/callback

ChatGPT connector URL:

https://your-public-host.example/mcp

ChatGPT redirect URI:

OAUTH_REDIRECT_URIS=

Do not put the ChatGPT redirect URI into the GitHub OAuth App.

Browser automation fails

Check whether Playwright browsers are installed:

npx playwright install

Also check whether the server is running under the Windows account that owns the browser/profile you expect to use.

Public hostname returns Cloudflare 530

The Cloudflare DNS and tunnel route may be correct, but the local tunnel connector is not connected.

Check that:

• the MCP server is listening on http://127.0.0.1:8789
• cloudflared is running
• the tunnel dashboard shows at least one active replica
• the tunnel route points to http://127.0.0.1:8789

ChatGPT can read but cannot perform a browser or desktop action

The local MCP server may be working correctly.

ChatGPT/OpenAI safety layers can still block some write, submit, send, post, authenticated browser, or desktop actions.

Treat this as a platform boundary first, then inspect server logs.