chatgpt-webui-mcp 0.1.0

package/.env.example

@@ -0,0 +1,50 @@
+# Required: value of the `__Secure-next-auth.session-token` cookie from chatgpt.com
+CHATGPT_SESSION_TOKEN=
+
+# Alternative (recommended): store the token in a file and point at it.
+CHATGPT_SESSION_TOKEN_FILE=
+
+# Transport mode defaults to camofox.
+# Set only if you explicitly want the fallback transport:
+# CHATGPT_TRANSPORT=httpcloak
+
+# Optional: alternate base URL
+CHATGPT_WEBUI_BASE_URL=https://chatgpt.com
+
+# Optional transport settings
+MCP_TRANSPORT=stdio
+MCP_SSE_HOST=127.0.0.1
+MCP_SSE_PORT=8791
+
+# Optional async job retention settings (for *_ask_async_* tools)
+CHATGPT_ASYNC_JOB_TTL_MS=86400000
+CHATGPT_ASYNC_JOB_MAX=150
+
+# Optional camofox settings (default transport)
+CHATGPT_BROWSER_BASE_URL=http://127.0.0.1:9377
+CHATGPT_USER_ID=chatgpt-webui-mcp
+CHATGPT_SESSION_KEY=chatgpt-webui
+CHATGPT_WAIT_TIMEOUT_MS=5400000
+CHATGPT_WORKSPACE=PRO
+# Backward-compatible aliases are still supported:
+# CHATGPT_CAMOFOX_BASE_URL, CHATGPT_CAMOFOX_USER_ID, CHATGPT_CAMOFOX_SESSION_KEY,
+# CHATGPT_CAMOFOX_WAIT_TIMEOUT_MS, CHATGPT_CAMOFOX_WORKSPACE
+# If your camofox server enables cookie import protection, set one of these:
+CHATGPT_CAMOFOX_API_KEY=
+CAMOFOX_API_KEY=
+
+# Optional httpcloak transport settings
+CHATGPT_HTTPCLOAK_PRESET=chrome-145
+CHATGPT_HTTPCLOAK_HTTP_VERSION=auto
+CHATGPT_HTTPCLOAK_TIMEOUT_SECONDS=30
+CHATGPT_HTTPCLOAK_PROXY=
+CHATGPT_HTTPCLOAK_TCP_PROXY=
+CHATGPT_HTTPCLOAK_UDP_PROXY=
+CHATGPT_HTTPCLOAK_TLS_ONLY=false
+CHATGPT_HTTPCLOAK_VERIFY_TLS=true
+CHATGPT_HTTPCLOAK_ALLOW_REDIRECTS=true
+CHATGPT_HTTPCLOAK_MAX_REDIRECTS=10
+CHATGPT_HTTPCLOAK_RETRY=3
+CHATGPT_HTTPCLOAK_PREFER_IPV4=false
+CHATGPT_HTTPCLOAK_ECH_CONFIG_DOMAIN=
+CHATGPT_HTTPCLOAK_QUIC_IDLE_TIMEOUT_SECONDS=30

package/INSTALL.md

@@ -0,0 +1,65 @@
+# chatgpt-webui-mcp - install
+
+this is a minimal standalone MCP server for ChatGPT WebUI.
+
+it uses `camofox` (UI-driven) by default for robust long-running tasks (pro, deep research).
+
+> important: this uses undocumented webui endpoints and a session cookie token. for personal/local tinkering only - not affiliated with openai.
+
+---
+
+## quick start (from source)
+
+```bash
+git clone https://github.com/Microck/chatgpt-webui-mcp.git
+cd chatgpt-webui-mcp
+npm install
+npm run build
+```
+
+set your session token:
+
+```bash
+export CHATGPT_SESSION_TOKEN="your_session_token_here"
+```
+
+run (stdio):
+
+```bash
+node dist/index.js
+```
+
+---
+
+## opencode config (recommended)
+
+add this to your OpenCode config (`~/.config/opencode/opencode.json`) under `mcp`:
+
+```json
+{
+  "mcp": {
+    "chatgpt-webui": {
+      "type": "local",
+      "enabled": true,
+      "timeout": 5400000,
+      "command": [
+        "node",
+        "/absolute/path/to/chatgpt-webui-mcp/dist/index.js"
+      ],
+      "environment": {
+        "CHATGPT_SESSION_TOKEN": "your_session_token_here",
+        "CHATGPT_BROWSER_BASE_URL": "http://127.0.0.1:9377",
+        "CHATGPT_WAIT_TIMEOUT_MS": "5400000"
+      }
+    }
+  }
+}
+```
+
+`camofox` is the default path. set `CHATGPT_TRANSPORT=httpcloak` only for optional advanced fallback mode.
+
+---
+
+## remote SSE (optional)
+
+if you want the server always-on (recommended for background runs), use the `deploy/systemd` templates in this repo.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Microck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+
+
+<h1 align="">chatgpt-webui-mcp</h1>
+
+<p align="">
+  mcp server for querying chatgpt (chatgpt.com) via webui session token.
+</p>
+
+<p align="">
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="license">
+  <img src="https://img.shields.io/badge/language-typescript-blue" alt="language">
+  <img src="https://img.shields.io/badge/mcp-sdk-orange" alt="mcp">
+  <a href="https://github.com/Microck/opencode-studio"><img src="https://img.shields.io/badge/opencode-studio-brown" alt="Add with OpenCode Studio" /></a>
+</p>
+
+---
+
+## quick start
+
+manual run:
+
+```bash
+CHATGPT_SESSION_TOKEN="your_token_here" npm install
+CHATGPT_SESSION_TOKEN="your_token_here" npm run build
+CHATGPT_SESSION_TOKEN="your_token_here" node dist/index.js
+```
+
+> important: this uses chatgpt's internal webui api with a session cookie. for personal/local tinkering only - not affiliated with openai.
+
+---
+
+### overview
+
+chatgpt-webui-mcp is a standalone MCP server that drives chatgpt.com via `camofox` (UI automation).
+
+it is built for long-running tasks (gpt-5.2 pro runs that take 1h+), deep research, and image generation mode.
+
+---
+
+### getting your session token
+
+1. open https://chatgpt.com and log in
+2. open devtools
+3. application -> cookies -> `https://chatgpt.com`
+4. copy the value of `__Secure-next-auth.session-token`
+
+---
+
+### configuration
+
+because this server uses `stdio` or `sse`, you configure it as a local command (or remote url) and pass the token via env.
+
+**mcp client config (claude desktop, opencode, etc)**
+
+ ```json
+ {
+   "mcpServers": {
+     "chatgpt-webui": {
+       "command": "node",
+       "args": ["/absolute/path/to/chatgpt-webui-mcp/dist/index.js"],
+        "timeout": 5400000,
+         "env": {
+           "CHATGPT_SESSION_TOKEN_FILE": "/path/to/session-token.txt",
+           "CHATGPT_BROWSER_BASE_URL": "http://127.0.0.1:9377",
+           "CHATGPT_WAIT_TIMEOUT_MS": "5400000"
+         }
+      }
+    }
+  }
+  ```
+
+legacy `CHATGPT_CAMOFOX_*` env vars are still supported for compatibility.
+`CHATGPT_TRANSPORT=httpcloak` is optional fallback mode for advanced/debug scenarios.
+
+---
+
+### opencode workflow (the natural language style)
+
+if you want to type commands like:
+
+- `with chatgpt webui on gpt 5.2 pro extended thinking: <prompt>`
+- `do deepresearch with chatgpt webui on <topic>`
+
+use this tool:
+
+| tool | what it does |
+|------|--------------|
+| `chatgpt_webui_command` | parses your sentence into the right call and runs it |
+
+example:
+
+```json
+{
+  "name": "chatgpt_webui_command",
+  "arguments": {
+    "command": "with chatgpt webui on gpt 5.2 pro extended thinking: write a 1-page memo about X",
+    "mode": "auto"
+  }
+}
+```
+
+---
+
+### long runs (recommended)
+
+use the unified tools:
+
+| tool | description |
+|------|-------------|
+| `chatgpt_webui_prompt` | main tool. `mode=auto` chooses wait vs background |
+| `chatgpt_webui_run` | check/wait for background runs (`run_id`) |
+
+why: deep research and gpt-5.2 pro can take a long time and may exceed a single client timeout. `mode=auto` returns a `run_id` for long jobs.
+
+---
+
+### image generation
+
+set `create_image=true` to switch chatgpt into image generation mode before sending the prompt.
+
+notes:
+- `image_urls` is best-effort (derived from page links + visited urls) and may be empty depending on how chatgpt renders images in the webui.
+- if you want a fallback screenshot (as a `data:image/...` url), set `CHATGPT_IMAGE_SCREENSHOT_FALLBACK=1` (can be large).
+- for reliable retrieval, you can also use the conversation_id and open the chatgpt UI.
+
+---
+
+### self-test
+
+```bash
+# env
+CHATGPT_SESSION_TOKEN="your_token_here" npm run self-test
+
+# cli flag
+npm run self-test -- --token "your_token_here"
+
+# file
+echo "your_token_here" > /tmp/chatgpt-session-token.txt
+npm run self-test -- --token-file /tmp/chatgpt-session-token.txt
+```
+
+---
+
+### remote deployment over tailscale (optional)
+
+if you want background runs to survive for a long time, run this server as an always-on SSE service.
+
+1) copy templates from this repo:
+- `deploy/systemd/chatgpt-webui-mcp.env.example`
+- `deploy/systemd/chatgpt-webui-mcp-sse.sh`
+- `deploy/systemd/chatgpt-webui-mcp.service`
+
+2) install and enable service (user service):
+
+```bash
+mkdir -p ~/.config ~/.config/systemd/user ~/.local/bin ~/.local/share/chatgpt-webui-mcp
+cp deploy/systemd/chatgpt-webui-mcp.env.example ~/.config/chatgpt-webui-mcp.env
+cp deploy/systemd/chatgpt-webui-mcp-sse.sh ~/.local/bin/chatgpt-webui-mcp-sse.sh
+cp deploy/systemd/chatgpt-webui-mcp.service ~/.config/systemd/user/chatgpt-webui-mcp.service
+chmod 600 ~/.config/chatgpt-webui-mcp.env
+chmod 755 ~/.local/bin/chatgpt-webui-mcp-sse.sh
+systemctl --user daemon-reload
+systemctl --user enable --now chatgpt-webui-mcp.service
+```
+
+3) point opencode (cloud host) to the endpoint:
+
+```json
+{
+  "mcp": {
+    "chatgpt-webui": {
+      "type": "remote",
+      "url": "http://<tailscale-ip>:8791/sse",
+      "enabled": true,
+      "timeout": 5400000,
+      "oauth": false
+    }
+  }
+}
+```
+
+---
+
+### tools
+
+| tool | description |
+|------|-------------|
+| `chatgpt_webui_session` | validate token and return session payload |
+| `chatgpt_webui_models` | list available models |
+| `chatgpt_webui_command` | natural-language command wrapper |
+| `chatgpt_webui_prompt` | unified prompt tool (wait/background) |
+| `chatgpt_webui_run` | check/wait for background runs |
+| `chatgpt_webui_ask` | direct wait-style prompt tool (legacy/simple) |
+
+---
+
+### project structure
+
+```
+chatgpt-webui-mcp/
+├── deploy/
+│   └── systemd/
+│       ├── chatgpt-webui-mcp.env.example
+│       ├── chatgpt-webui-mcp-sse.sh
+│       └── chatgpt-webui-mcp.service
+├── src/
+│   ├── index.ts               # MCP server
+│   └── chatgpt-webui-client.ts # WebUI automation client
+├── package.json
+├── tsconfig.json
+├── .env.example
+├── .gitignore
+├── LICENSE
+├── INSTALL.md
+└── README.md
+```
+
+---
+
+### license
+
+mit
+
+---
+
+### author
+
+[Microck](https://github.com/Microck)

package/deploy/systemd/chatgpt-webui-mcp-sse.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ENV_FILE="${ENV_FILE:-$HOME/.config/chatgpt-webui-mcp.env}"
+
+if [ ! -f "$ENV_FILE" ]; then
+  echo "missing env file: $ENV_FILE" >&2
+  exit 1
+fi
+
+set -a
+# shellcheck disable=SC1090
+source "$ENV_FILE"
+set +a
+
+exec node "${CHATGPT_WEBUI_MCP_DIST:-$HOME/.local/share/chatgpt-webui-mcp/dist/index.js}"

package/deploy/systemd/chatgpt-webui-mcp.env.example

@@ -0,0 +1,28 @@
+# ChatGPT session cookie token
+CHATGPT_SESSION_TOKEN=
+
+# transport defaults to camofox.
+# set only if you explicitly want fallback mode:
+# CHATGPT_TRANSPORT=httpcloak
+
+# ChatGPT base URL
+CHATGPT_WEBUI_BASE_URL=https://chatgpt.com
+
+# camofox browser server
+CHATGPT_BROWSER_BASE_URL=http://127.0.0.1:9377
+CHATGPT_USER_ID=chatgpt-webui-mcp
+CHATGPT_SESSION_KEY=chatgpt-webui
+CHATGPT_WAIT_TIMEOUT_MS=5400000
+CHATGPT_WORKSPACE=PRO
+
+# if camofox cookie import is protected
+CHATGPT_CAMOFOX_API_KEY=
+
+# MCP server transport
+MCP_TRANSPORT=sse
+MCP_SSE_HOST=0.0.0.0
+MCP_SSE_PORT=8791
+
+# background run retention
+CHATGPT_ASYNC_JOB_TTL_MS=86400000
+CHATGPT_ASYNC_JOB_MAX=150

package/deploy/systemd/chatgpt-webui-mcp.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=chatgpt-webui-mcp (SSE)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+Environment=ENV_FILE=%h/.config/chatgpt-webui-mcp.env
+Environment=CHATGPT_WEBUI_MCP_DIST=%h/.local/share/chatgpt-webui-mcp/dist/index.js
+ExecStart=%h/.local/bin/chatgpt-webui-mcp-sse.sh
+Restart=on-failure
+RestartSec=2
+
+[Install]
+WantedBy=default.target

package/dist/chatgpt-webui-client.d.ts

@@ -0,0 +1,43 @@
+export type ChatgptWebuiClientOptions = {
+    baseUrl?: string;
+    sessionToken?: string;
+    transport?: "camofox" | "httpcloak";
+};
+export type AskInput = {
+    prompt: string;
+    model?: string;
+    modelMode?: "auto" | "instant" | "thinking" | "pro";
+    reasoningEffort?: "none" | "standard" | "extended";
+    deepResearch?: boolean;
+    deepResearchSiteMode?: "search_web" | "specific_sites";
+    createImage?: boolean;
+    waitTimeoutMs?: number;
+    workspace?: string;
+    conversationId?: string;
+    parentMessageId?: string;
+};
+export type AskOutput = {
+    text: string;
+    conversationId: string | null;
+    parentMessageId: string | null;
+    model: string | null;
+    imageUrls?: string[];
+};
+type SessionPayload = {
+    accessToken?: string;
+    user?: {
+        id?: string;
+        name?: string;
+        email?: string;
+    };
+    expires?: string;
+};
+export declare class ChatgptWebuiClient {
+    #private;
+    constructor(options?: ChatgptWebuiClientOptions);
+    close(): void;
+    getSession(): Promise<SessionPayload>;
+    getModels(): Promise<unknown>;
+    ask(input: AskInput): Promise<AskOutput>;
+}
+export {};