ChatGPT Local Coder

Turn ChatGPT web into a local coding agent — files, shell, git, patches, 40+ MCP tools.

Quick Start · GUI · Connect ChatGPT · Tools · Tunnel · Troubleshooting · Tiếng Việt

ChatGPT Local Coder is a self-hosted MCP server that gives ChatGPT (and any MCP client) full access to your machine — read and edit code, run npm test, manage git, apply unified diffs, and explore projects with glob / grep.

The core server is CLI-first with no required desktop app or vendor lock-in. An optional Windows GUI is included for setup and daily start/stop tasks.

┌─────────────────┐     HTTPS      ┌──────────────────┐     localhost     ┌─────────────────────┐
│   ChatGPT Web   │ ─────────────► │  Tunnel (opt.)   │ ────────────────► │  chatgpt-local-coder │
│ Developer Mode  │                │ OpenAI / CF      │      :3000/mcp    │  40+ MCP tools       │
└─────────────────┘                └──────────────────┘                   └──────────┬──────────┘
                                                                                    │
                                         ┌──────────────────────────────────────────┼──────────┐
                                         ▼                    ▼                    ▼          ▼
                                   Filesystem              Shell + Git         Background    Project
                                   read/write/patch        status/diff/commit   processes     context

✨ Why this project

Built for ChatGPT Developer Mode with optimized tool annotations (fewer permission popups) and OpenAI Secure MCP Tunnel support (stable URL, no connector re-wiring every restart).

Related MCP server: DevSpace

🚀 Quick Start

Requirements: Node.js 18+, npm, Git (optional, for git tools)

git clone https://github.com/colin-dmme/chatgpt-local-coder.git
cd chatgpt-local-coder
copy .env.example .env          # edit WORKSPACE_PATH
npm install
npm run build
.\start.ps1

Server runs at http://localhost:3000 — health check: http://localhost:3000/health

git clone https://github.com/colin-dmme/chatgpt-local-coder.git
cd chatgpt-local-coder
cp .env.example .env
npm install && npm run build
npm start

🖥️ Optional Windows GUI

The repository includes chatgpt-local-coder-gui, a small PySide6 launcher for users who prefer not to edit .env or start the server/tunnel manually.

cd chatgpt-local-coder-gui
uv sync
uv run python main.py

The GUI can:

• choose WORKSPACE_PATH

• save local account/profile settings

• configure the OpenAI Tunnel ID and runtime API key

• start/focus the MCP server and tunnel windows

• open the ChatGPT connector settings page

chatgpt-local-coder-gui/profiles.json is intentionally gitignored because it may contain account names, tunnel IDs and API keys. Never publish that file.

🔌 Connect ChatGPT

1. Enable Developer Mode

1. Open ChatGPT → Settings → Apps & Connectors

2. Under Advanced, enable Developer mode

2. Expose your server (pick one tunnel)

See Tunnel options below. You need a public HTTPS URL pointing to http://localhost:3000/mcp.

3. Create a connector

1. Settings → Connectors → Create

2. Fill in:

3. Create → verify tools appear in the list

4. Use in chat — must tag the connector

Every message that should use local tools must include the connector. If you skip this, ChatGPT only uses built-in tools, may show "Looking for available tools" / "Đang tìm các công cụ có sẵn", then "Error in message stream" / "Lỗi trong luồng tin nhắn" — with no error in server logs (the MCP server was never called).

How to tag (pick one):

1. Before sending: New chat → + (tools) → More → enable Local Coder (connector stays on for that chat).

2. In the message: type @ and choose Local Coder (or your connector name) so it appears as a pill/chip above the input.

Then send your prompt. You should see tool permission prompts or MCP activity — not a dead stream with no server log.

Example prompts (after tagging):

• "Read package.json and explain the dependencies"

• "Run npm test and fix any failures"

• "Find all TODO comments with grep and summarize"

Tip: After server updates or restarts → Refresh the connector and start a new chat (re-tag the connector).
Avoid clicking "Always allow" on permission popups — it can reset the MCP session. Configure permissions in Settings → Apps instead.

🌐 Tunnel options

Option A — OpenAI Secure MCP Tunnel (recommended)

Stable tunnel ID — connector URL never changes.

# Terminal 1
.\start.ps1 -Force

# Terminal 2 — first time only
.\openai-tunnel-init.bat    # enter tunnel_id + Runtime API key from OpenAI Platform

# Every time after
.\openai-tunnel.bat

Get credentials: OpenAI Platform → Tunnels

In ChatGPT Connectors: Connection type → Tunnel → paste your tunnel_… ID.

Option B — Cloudflare Quick Tunnel

Free, but URL changes on every restart (update connector each time).

# Terminal 1
.\start.bat

# Terminal 2
.\tunnel.bat    # copy https://….trycloudflare.com into connector URL

Install cloudflared: winget install Cloudflare.cloudflared

🧰 Tools

40+ tools with structured JSON responses { ok, tool, summary, data }.

Onboarding (call these first)

Filesystem

Shell

Git

Claude Code ↔ MCP mapping

⚙️ Configuration

Copy .env.example → .env:

PORT=3000
WORKSPACE_PATH=C:\Users\You\projects\my-app
CHATGPT_AUTO_APPROVE=true
SHELL_TIMEOUT=120
MCP_SESSION_RECOVERY=true

# OpenAI Secure Tunnel (optional)
OPENAI_TUNNEL_ID=
OPENAI_TUNNEL_API_KEY=

Full machine access is enabled by default. WORKSPACE_PATH only sets the default cwd — absolute paths like D:\Projects\… work everywhere.

🏗️ Architecture

src/
├── index.ts                 # Express + MCP session manager
├── server-factory.ts        # Tool registration
├── lib/
│   ├── mcp-session-manager.ts   # Session recovery, TTL
│   ├── patch.ts             # apply_patch engine
│   └── persistent-shell.ts  # Stateful shell
└── tools/
    ├── filesystem.ts        # 18 tools
    ├── shell.ts             # 8 tools
    ├── git.ts               # 11 tools
    └── context.ts           # agent_status, project_context

• Transport: MCP Streamable HTTP (/mcp and /)

• Session: Stateful with auto-recovery when ChatGPT holds a stale session ID

• Output: Structured JSON from every tool

🧪 Development

npm run build          # compile TypeScript
npm test               # patch + tool unit tests
npm run dev            # watch mode (tsx)
node scripts/test-mcp-session.mjs   # integration test (server must be running)

🔒 Security

This server grants full access to your machine — files, shell, git. Only expose it through a tunnel you control. Never share your connector URL or tunnel API keys.

• .env, GUI profiles, generated tunnel profiles, state/checkpoints, logs and common key/certificate files are gitignored

• Keep real upstream MCP paths/credentials in a local file such as profiles/mcp-upstream.local.json; the committed profiles/mcp-upstream.json is a safe starter config

• .env.example must contain placeholders only — never real tunnel IDs, API keys, usernames or machine-specific paths

• Before publishing a fork, run a secret scan over the files that Git will actually track

• Audit log: .mcp-audit.log (optional, configurable)

• Use on a trusted network / personal machine only

🩺 Troubleshooting

See also AGENTS.md for agent onboarding and apply_patch format.

📚 References

• Model Context Protocol

• MCP TypeScript SDK

• ChatGPT Apps SDK

• OpenAI Secure MCP Tunnel

📄 License

MIT — use freely, attribution appreciated.

⭐ Support

If this saves you time, star the repo — it helps others find it.

🇻🇳 Tiếng Việt

ChatGPT Local Coder biến ChatGPT web thành agent code trên máy bạn qua MCP.

git clone https://github.com/colin-dmme/chatgpt-local-coder.git
cd chatgpt-local-coder
copy .env.example .env
npm install && npm run build
.\start.ps1                    # terminal 1
.\openai-tunnel.bat            # terminal 2 (tunnel cố định)

ChatGPT: Settings → Connectors → tạo connector → chọn tunnel → Refresh → chat mới.

Bắt buộc tag connector mỗi chat: Chat mới → + → More → bật connector, hoặc gõ @ + tên connector trong ô chat. Nếu không tag, ChatGPT báo "Đang tìm các công cụ có sẵn" rồi "Lỗi trong luồng tin nhắn" — server không có log lỗi vì MCP chưa được gọi.

WORKSPACE_PATH: đặt đúng thư mục project (không phải thư mục chatgpt-local-coder). Server tự đọc CLAUDE.md / AGENTS.md giống Claude Code.

Lưu ý: Không bấm "Luôn cho phép" trên popup — cấu hình quyền ở Settings → Apps. Sau khi restart server: Refresh connector + mở chat mới + tag lại connector.

Chi tiết cho AI agent: AGENTS.md