Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/chatgpt-local-agent-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Most AI coding workflows hit the same wall eventually. ChatGPT can suggest what command to run, propose a patch, or ask for a log file — but the actual project, the real repo, the broken build output, and the live browser session all live on your computer. chatgpt-local-agent-mcp closes that gap. It is a local MCP server for Windows that gives ChatGPT supervised access to your filesystem, shell, Git, browser, screen, and desktop through the Model Context Protocol. You keep full visibility and control; ChatGPT gains the ability to work against the same local reality you are working with instead of guessing from copied snippets.

​
The core concept

ChatGPT stays the brain. This gives it supervised hands on your PC. With the server running, ChatGPT can read and write files, apply patches, run build commands, inspect Git diffs, open browser sessions, capture screenshots, and operate the desktop — all from within a normal ChatGPT conversation. Every capability goes through a local server you own, bound to 127.0.0.1 by default, with OAuth gating all remote access.
The goal is not to make ChatGPT autonomous. The goal is to let ChatGPT work with the same local context you are working with, while you supervise what it does.

​
Two setup paths

There are two distinct things to set up, and they should be done in order. Path A — local-only smoke test proves the server starts and the dashboard responds. No Cloudflare, no GitHub OAuth App, no ChatGPT connector, and no public URL are involved. This is always the right first step. 
Windows PC
  -> http://127.0.0.1:8789
  -> local MCP server
  -> local dashboard / health checks
Path B — full remote ChatGPT connector exposes the server through an authenticated HTTPS endpoint so ChatGPT can reach it as a remote MCP connector. This step is deliberately more explicit because it connects a remote client to real local machine capabilities. 
ChatGPT
  -> your HTTPS hostname
  -> Cloudflare Tunnel
  -> http://127.0.0.1:8789
  -> local MCP server
  -> your Windows PC
Do not skip Path A. If the local server does not start cleanly and the dashboard does not open, there is no point configuring OAuth or a public tunnel yet.

​
Tool categories

The server registers tools across eight categories, each controlled by a dedicated MCP scope:
CategoryScopeWhat it covers
Workspacemcp:readWorkspace info, profile listing
Filesystemmcp:read / mcp:write / mcp:patch / mcp:deleteRead, write, patch, copy, move, delete, search, hash, tree, stat
Gitmcp:gitStatus, diff, commit
Shellmcp:shellCommand execution in a workspace directory
Processmcp:processStart, stop, kill, port list, log tail, wait for port
Browsermcp:browserSessions, navigation, snapshots, console, network, screenshots, CDP attach
Screenmcp:screenScreenshots, OCR hook, window listing
Desktopmcp:desktopMouse and keyboard automation
Use the narrowest set of scopes that covers what you actually need. Add broader capabilities only when you have a specific reason.

​
Security model

Security is layered across four mechanisms:
  1. OAuth controls who can connect. GitHub is the identity provider. After a GitHub login, the server checks an allowlist (ALLOWED_GITHUB_LOGINS) before issuing a local MCP authorization code. ChatGPT then connects as the MCP OAuth client using its own separate client credentials.
  2. Scopes limit tool categories. Each tool belongs to a scope. An access token that was issued without mcp:shell, for example, cannot call shell tools regardless of what ChatGPT requests.
  3. Workspace profiles restrict filesystem paths. By default the server creates one profile per detected drive root (e.g. C:\, D:\), giving full-machine access. Custom profiles defined via GPT_FS_MCP_WORKSPACE_PROFILES_JSON restrict all filesystem, shell, and process tools to declared root paths and their allowed policy modes.
  4. Policy modes limit destructive operations. The GPT_FS_MCP_MAX_POLICY_MODE setting caps the highest-risk operations the server will execute. Shell and process policies (GPT_FS_MCP_SHELL_POLICY, GPT_FS_MCP_PROCESS_POLICY) can be set to workspace_guarded to keep commands anchored to workspace paths.
For a safer first remote test, define a custom workspace profile pointing to a single repo folder, set shell and process policies to workspace_guarded, and confirm the local dashboard shows the expected profile before connecting ChatGPT.
The system is designed to be capable, not sandboxed. Browser CDP attach can interact with active logged-in sessions. Desktop tools move the real mouse and press real keys. Shell and process tools run with the permissions of the Windows account that starts the server. Treat access like you would treat a human assistant sitting at your keyboard.

​
Quick navigation

Quickstart

Install the server, run a local smoke test, and confirm the dashboard works in under 10 minutes.

Path A — Local Smoke Test

Step-by-step guide to proving the local server starts before configuring any remote access.

Path B — Remote Connector

Configure GitHub OAuth, Cloudflare Tunnel, and ChatGPT connector credentials for remote access.

Tools Overview

Browse all 50+ registered tools across the eight tool categories with their scopes and policy modes.

​
What ChatGPT can help with

Once the server is running and connected, ChatGPT can assist with tasks like:
  • Inspect a local project — read files, list directories, and build a map of a codebase
  • Apply patches and write or update files directly without copy-pasting
  • Run build commands, test suites, and diagnostic scripts and read the output
  • Inspect Git status, diffs, and history, and create commits
  • List running processes and open ports
  • Tail log files and wait for services to become available
  • Open browser automation sessions, navigate pages, and capture console or network output
  • Take screenshots and inspect what is currently visible on screen
  • List open windows and use mouse or keyboard actions when needed
  • Show live server and workspace status through the local dashboard
ChatGPT still has its own safety layer. Some write, submit, send, post, authenticated browser, or desktop actions may be blocked or require confirmation on the ChatGPT/OpenAI side. Those limits are enforced by the platform, not by this server.

Build docs developers (and LLMs) love

Get started for freeTalk to us