# Chatgpt Code mcp

**Local-first, self-hosted developer Model Context Protocol (MCP) server** for reading and editing files, running commands, inspecting processes, and working with local projects.

The **CLI MCP server is the main project**. The optional **Chrome extension** and **Chatty desktop GUI** are included but are **experimental**. You do **not** need either graphical client to use the MCP.

> **Testing status:** Developed and used on **Linux with Hyprland**. Core Node.js functionality aims to be portable to **Linux, macOS, and Windows**, but **macOS and Windows have not been tested**; support there is experimental. Hyprland computer use and Chrome control have **not been thoroughly tested**, even on Linux. Expect bugs, missing permissions, compatibility issues, and security-sensitive edge cases.

## Quick start: MCP only (no GUI)

Requires Node.js 20+ and npm. Clone **your own copy**, then run:

```bash
git clone https://github.com/YashMahawa/Chatgpt-Code-mcp.git
cd Chatgpt-Code-mcp
npm ci
cp .env.example .env
```

**Stdio MCP** (the simplest local integration):

```bash
npm run stdio
```

Configure your MCP-capable client's command as `node` and arguments as `/absolute/path/to/Chatgpt-Code-mcp/src/server.js --stdio`. Set the working directory to the clone. There is no Chrome extension, desktop application, tunnel, or public URL involved.

**Local HTTP MCP** (Streamable HTTP + legacy SSE):

```bash
# First: generate your OWN secret locally and save it as MCP_AUTH_TOKEN in .env.
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
npm start
```

Server: `http://127.0.0.1:3001/mcp`. The server binds to loopback by default. For HTTP use, a configured secret enables Bearer or `X-API-Key` authentication; the full secret must stay private.

### Connect to ChatGPT or another remote MCP client

You must provide your **own** private HTTPS endpoint. This repository deliberately contains **no personal MCP URL, tunnel ID, Cloudflare credentials, tokens, or preconfigured remote host**.

1. Create your own named Cloudflare Tunnel or an equivalent authenticated HTTPS reverse proxy. Configure it to forward to `http://127.0.0.1:3001`. Do not copy anyone else's hostname or tunnel configuration.
2. Set `MCP_AUTH_TOKEN` to a strong, uniquely generated value and `TUNNEL_DOMAIN` to **your own** public hostname in your untracked `.env` file. The script refuses to start a public tunnel without a secret.
3. If using Cloudflare, install `cloudflared`, configure **your own** named tunnel and its `~/.cloudflared/config.yml`, then start `npm run tunnel`.
4. Point your MCP client to `https://your-own-hostname.example/mcp`. Supply the secret in an `Authorization: Bearer ...` header where supported; if the client only accepts a URL, the server also supports `?key=<YOUR_SECRET>`. **That complete URL is a password. Never post it in an issue, README, screenshot, commit, or log.**

A public domain alone is **not** authentication. Keep both your endpoint and secret under your control. Avoid enabling unauthenticated mode.

## MCP capabilities

- Read, create, edit, patch, search, and list local files.
- Run shell commands; inspect their output; stop tracked background processes.
- Inspect GitHub working directories using local tools where available.
- Optional Playwright-managed **isolated browser**, separate from your main Chrome profile.
- Optional Chrome extension integration to access **user-approved tabs** on the main browser (experimental).
- Optional Linux/Hyprland screenshots, keyboard, mouse, and monitor control (experimental; disabled by default).
- Optional Caelestia indexed search, **only if independently installed** on a compatible Linux system.

**Security boundary:** MCP tools execute as the operating-system user running the server. They can read or change anything that user can access. Never expose the endpoint without authentication, and do not attach it to an untrusted AI client.

## Optional experimental clients

| Component | Location | State |
|---|---|---|
| CLI MCP server | `src/server.js` | Main supported entry point; Linux tested |
| Browser-local dashboard | `web/` + `src/dashboard.js` | Prototype UI, Linux tested |
| Chrome extension | `extension/chrome-main/` | **Experimental**, requires local pairing |
| Desktop GUI | `desktop/` | **Experimental** Tauri + React client; Linux/Hyprland prototype |
| Physical computer use | `src/computerUse.js` | **Experimental**, Linux/Hyprland only |

**Chrome extension:** start `npm run dashboard`, which initializes a local bridge and generates a local pairing secret. Copy `extension/chrome-main/config.example.js` to `config.js`, substitute the bridge secret generated **on your own device** in `~/.local/state/chatgpt-agent-mcp/chrome/bridge-token`, and load `extension/chrome-main` using Chrome's **Load unpacked** extension option. `config.js` is Git-ignored. Review the requested permissions: the extension uses Chrome debugging capabilities and can act in tabs you authorize. See [experimental browser notes](docs/CHROME.md).

**Desktop client:** see [desktop setup notes](docs/DESKTOP.md). The desktop UI is **rough and visually unfinished**. It has functional gaps, and the original author has stopped prioritizing its redesign. The author expects closer Codex and ChatGPT workflow convergence around December 2026; this is an expectation, **not a verified OpenAI release commitment**. Contributions are welcome, but this repo does not promise a polished GUI.

## Platform compatibility

| Feature | Linux + Hyprland | Linux other desktops | macOS | Windows |
|---|---|---|---|---|
| Node MCP stdio/HTTP, files & processes | Used | Experimental | **Untested** | **Untested** |
| Browser-local dashboard | Used | Experimental | **Untested** | **Untested** |
| Chrome extension / Chrome use | Early prototype | Experimental | **Untested** | **Untested** |
| Tauri GUI | Early prototype | Experimental | **Untested** | **Untested** |
| Physical desktop / screenshots | **Experimental** | Not implemented | Not implemented | Not implemented |
| systemd background service | Available | Available | Not applicable | Not applicable |

The CLI interface is written in Node.js, but shell commands, installed utilities, executable names, file permissions and environment setup may differ across OSes. Cross-platform feature parity has **not** been verified.

## Background service and optional full access (Linux)

See [Linux systemd setup and privileged-access warning](docs/PRIVILEGED_ACCESS.md). The project includes a service template; it does **not** install or enable it automatically.

The opt-in `NoNewPrivileges=false` systemd override is documented there for users who deliberately require sudo elevation through the MCP. It is **not** the default. Passwordless sudo is a separate operating-system policy and is never configured by this repo.

## Privacy

This repository contains **only source and sanitized public documentation**, created as a brand-new Git history. It excludes local runtime state, stored chats, account credentials, Cloudflare tunnel files, personal hostnames, pairing secrets, local workspace diagnostics, and build outputs. **Set up all secrets and URLs yourself.**

Report security concerns privately. See [SECURITY.md](SECURITY.md).

## Development

`npm run check` performs a small JavaScript syntax check. `npm test` runs a limited subset of Node tests. These do not prove Chrome or desktop automation is safe. Builds are **not** included in this repository; build the optional desktop client yourself if needed.

## License and attribution

MIT for this project's source (see [LICENSE](LICENSE)). Some desktop visual ideas derive from MonoCode; its original attribution and MIT notice are retained under `desktop/`. No personal account assets or prebuilt UI bundles are included.