webgpt MCP

日本語 | English

Local Streamable HTTP MCP server for sending prompts from Codex to ChatGPT Web Pro extension, plus repository-safe task handoff.

This project intentionally does not expose arbitrary shell execution, patch application, direct Codex invocation, deleting files, committing, or pushing through MCP tools.

日本語

概要

webgpt MCP は、Codex から ChatGPT Web の Pro 拡張 へpromptを投げ、結果をCodexへ返すためのローカルMCPサーバーです。

このrepoはChatGPT Web Pro拡張連携と、.ai/tasks、.ai/results、.ai/reviews、.ai/logs を使った共有作業台だけを扱います。

主ワークフローはCodex主導です。Codexがローカルrepo文脈を集め、必要に応じてChatGPT WebのPro拡張に計画を依頼し、その出力を受け取ってローカルに保存し、実装と検証を進めます。ChatGPT Webから直接Codexを呼び出す必要はありません。

アーキテクチャ

Codex CLI / IDE
  -> webgpt-mcp /mcp-codex
     -> run_pro_prompt
     -> Chrome / ChatGPT Web Pro extension
     <- Pro planning output
  -> registered local repositories
  -> .ai/pro-outputs
  -> .ai/tasks .ai/results .ai/reviews .ai/logs
  -> implementation and verification

Optional ChatGPT connector:
ChatGPT Web
  -> HTTPS tunnel
  -> webgpt-mcp /mcp
  -> safe planner/reviewer tools only

必要条件

• Node.js 20+

• pnpm

• macOS launchdは本番常駐化に任意

• Cloudflare TunnelはChatGPT Web connectorを使う場合だけ任意

最小セットアップ

.env は不要です。clone後はこれだけで起動できます。

pnpm install
pnpm dev

デフォルトでは http://127.0.0.1:8788 で起動します。Codex側で webgpt を使うよう指示すると、Codexが現在のrepoを自動登録します。

Use webgpt MCP.
Register the current repository automatically if needed, then call list_projects and repo_tree.

登録すると、このMCPサーバーの作業ディレクトリに projects.local.json が自動生成・更新されます。手でallowlistを管理する必要はありません。以後は各toolで projectId を渡せます。省略時はdefault projectを使います。

{ "projectId": "my-project", "path": "package.json" }

対象repoには必要に応じて次のディレクトリが作成されます。

.ai/tasks
.ai/results
.ai/reviews
.ai/logs
.ai/context

AGENTS.md が存在しない場合のみ作成します。既に存在する場合は上書きせず、.ai/context/webgpt-workflow.md を作成します。

任意設定

全ての MCP_* は任意です。必要になったものだけ .env に書きます。

cp .env.example .env
chmod 600 .env

よく使う設定:

MCP_PORT=8788
MCP_PUBLIC_PIN=<short-lived-pin>
MCP_CODEX_TOKEN=<long-random-token>
MCP_ALLOWED_ORIGINS=https://chatgpt.com
MCP_PROJECTS_FILE=/absolute/path/to/projects.local.json
MCP_DEFAULT_PROJECT_ID=my-project

MCP_PUBLIC_PIN を設定すると、/mcp の全tool callで pin 入力が必要になります。ChatGPT endpointをトンネル公開する場合は設定してください。

MCP_CODEX_TOKEN を設定すると、/mcp-codex は Authorization: Bearer $MCP_CODEX_TOKEN を要求します。localhostだけで使う最小構成では未設定でも動きます。

MCP_PROJECTS_FILE は自動生成されるregistryの保存先を変えたい場合だけ使います。

Codex設定

自動設定:

pnpm run codex:configure

.env や MCP_CODEX_TOKEN がなくても動きます。tokenがある場合だけ bearer_token_env_var を ~/.codex/config.toml に追加します。

tokenなしの最小設定:

[mcp_servers.webgpt]
url = "http://127.0.0.1:8788/mcp-codex"
startup_timeout_sec = 20
tool_timeout_sec = 1200
enabled = true
default_tools_approval_mode = "prompt"

tokenありの設定:

[mcp_servers.webgpt]
url = "http://127.0.0.1:8788/mcp-codex"
bearer_token_env_var = "MCP_CODEX_TOKEN"
startup_timeout_sec = 20
tool_timeout_sec = 1200
enabled = true
default_tools_approval_mode = "prompt"

Codex用プロンプト例:

Use webgpt MCP.
Automatically register the current repository if needed.
List projects.
List open tasks.
Pick the highest priority open task.
Read it.
Claim it.
Implement only that task.
Run available verification commands.
Run typecheck, lint, test, and build when available.
Write the result with write_result.
Do not edit unrelated files.
Do not skip verification.

本番運用

本番相当のローカル常駐では、tsx ではなくビルド済みの dist/index.js を起動します。

pnpm build
pnpm start

デーモン化前の検証:

pnpm run doctor
pnpm run prod:verify

macOS launchdに登録:

pnpm run launchd:install

停止・削除:

pnpm run launchd:uninstall

状態確認:

launchctl print "gui/$(id -u)/local.webgpt-mcp"
pnpm run healthcheck

ログ:

.ai/logs/server.stdout.log
.ai/logs/server.stderr.log
.ai/logs/mcp-audit.jsonl

エンドポイント

GET  /healthz
GET  /readyz
POST /mcp
GET  /mcp
POST /mcp-codex
GET  /mcp-codex

/mcp-codex はCodex向けです。MCP_CODEX_TOKEN が設定されている場合はbearer認証が必要です。

/mcp はChatGPT向けです。公開しないなら使う必要はありません。公開する場合は MCP_PUBLIC_PIN を設定し、Cloudflare Tunnelや別のaccess layerで保護してください。

Tools

ChatGPT /mcp tools:

list_projects
repo_tree
read_file
grep_repo
git_diff
create_task
list_tasks
read_task
read_result
write_review

Codex /mcp-codex tools:

register_project
list_projects
pro_browser_status
prepare_pro_browser
run_pro_prompt
repo_tree
read_file
grep_repo
read_task
list_tasks
claim_task
write_result
read_result
git_diff
run_check

run_check は対象repoの package.json に存在する typecheck、lint、test、build scriptだけを実行します。任意コマンド入力は受け付けません。

MCP Inspector

npx @modelcontextprotocol/inspector@latest

テスト対象:

http://127.0.0.1:8788/mcp
http://127.0.0.1:8788/mcp-codex

確認項目:

• list_projects が成功する

• register_project で対象repoを登録できる

• 登録後に repo_tree、read_file、grep_repo が成功する

• create_task で .ai/tasks/*.md が作られる

• claim_task と write_result で .ai/results/*.md が作られる

• run_check がallowlist済みscriptだけを実行する

• MCP_PUBLIC_PIN 設定時は間違ったPINが失敗する

• MCP_CODEX_TOKEN 設定時はbearerなしの /mcp-codex が401になる

Cloudflare Tunnel

ChatGPT connectorを使う場合だけ必要です。ローカル専用運用では不要です。

開発用quick tunnel:

pnpm dev
pnpm tunnel:quick

永続Tunnelでは、例えば mcp.example.com を http://localhost:8788 に向け、ChatGPT connector URLに https://mcp.example.com/mcp を設定します。

ChatGPT connector手順:

1. MCP_PUBLIC_PIN を設定する。

2. MCPサーバーを起動する。

3. Cloudflare Tunnelを起動する。

4. 発行されたHTTPS URLをコピーする。

5. ChatGPTでDeveloper modeを有効にする。

6. Connectorを作成する。

7. Connector URLに https://<cloudflare-tunnel-host>/mcp を設定する。

8. 新しいchatでconnectorを有効にする。

9. そのsession用の短命 MCP_PUBLIC_PIN をChatGPTに伝える。

CodexからChatGPT Pro拡張を使う

Codexが高負荷の計画作成を必要とする場合に使います。

webgpt MCPの主機能です。Codexから run_pro_prompt を呼ぶと、MCPサーバーがGoogle Chrome上のChatGPT Webを操作し、Pro 拡張 にpromptを送信し、完了まで待ち、結果を .ai/pro-outputs に保存してCodexへ返します。

初回や失敗時は pro_browser_status で、使用中backend、Chrome profile directory、必要な権限を確認してください。

デフォルトbackendは playwright-chrome です。Chrome 136以降は通常のChromeデータディレクトリに対する --remote-debugging-port が無視されるため、MCPはデフォルトで ~/.webgpt-mcp/chrome-user-data という非標準user-data-dir内の --profile-directory=webgpt を起動して接続します。これは専用Chromeアプリではなく、通常のGoogle Chromeアプリで動くMCP用Chrome profileです。初回だけログインが必要な場合は、まず prepare_pro_browser を呼び、開いた webgpt Chrome profileでChatGPTへログインしてから run_pro_prompt を実行してください。

MCP_PRO_USE_SYSTEM_CHROME_PROFILE=true を設定すると通常のChrome profile root配下を使う実験モードになります。ただしChrome 136以降ではCDPが無視されるため、通常は使わないでください。通常終了がブロックされ、Chromeを閉じてもよい状況では forceChromeRestart: true も指定できます。この場合はGoogle Chrome本体へSIGTERMを送りますが、SIGKILLは使いません。

既にログイン済みのChromeを --remote-debugging-port 付きで起動している場合は、run_pro_prompt / prepare_pro_browser に cdpEndpoint: "http://127.0.0.1:<port>" を渡すか、.env に MCP_PRO_CDP_ENDPOINT を設定できます。endpointはlocalhost限定です。

互換用に MCP_PRO_BROWSER_MODE=chrome-applescript も残しています。この場合のみmacOSのAutomation/Accessibility権限が必要です。

Use webgpt MCP.
Automatically register the current repository if needed.
Call pro_browser_status.
If login is required, call prepare_pro_browser and log into ChatGPT in the opened Chrome window.
Call run_pro_prompt with:
- title: "<short title>"
- modelLabel: "Pro 拡張"
- chromeProfileDirectory: "webgpt"
- allowChromeRestart: true
- forceChromeRestart: false
- timeoutSec: 1200
- keepBrowserOpen: true
- confirmSendToChatGpt: true
- prompt: |
  あなたはChatGPT Pro拡張として、Codex実装者に渡す計画を作る役割です。

  目的: <Codexが実装する目的>

  出力要件:
  - 日本語
  - 具体的な実装手順を5〜8項目
  - セキュリティ境界と失敗時の扱い
  - 最初の行を PRO_PLAN_START、最後の行を PRO_PLAN_END にする
  - 余計な前置きは不要

保存先例:

.ai/pro-outputs/PRO-YYYYMMDD-HHMMSS-<slug>.md
.codex/pro-plan/responses/<task_id>.md
docs/implementation/<task_id>/PRO_PLAN.md

セキュリティ

• デフォルトはlocalhost専用の最小構成です。endpointを公開しない運用なら .env は不要です。

• /mcp はsafe-by-defaultです。shell、patch適用、削除、ソース書き込みはできません。

• /mcp を公開する場合は MCP_PUBLIC_PIN を設定してください。

• /mcp-codex をlocalhost外から使う場合は MCP_CODEX_TOKEN を設定してください。

• Streamable HTTPのDNS rebinding対策として、Origin headerが存在する場合は許可済みoriginだけ受け付けます。

• ファイルパスは登録されたrepo配下に解決されます。path traversalとsymlink escapeは可能な範囲で拒否します。

• envファイル、secret/tokenを含むpath、PEM/key、.git、node_modules、build output、Next output、coverageは読み取り拒否対象です。

• readとdiffはbyte上限付きで、truncateされた場合はflagを返します。

• audit logは .ai/logs/mcp-audit.jsonl にJSON Linesとして記録されます。

• PIN、bearer token、prompt本文はaudit logへ記録しません。

Production TODO: 公開運用する場合はPINではなくOAuth 2.1、Cloudflare Access、Auth0、Stytchなどのaccess layerへ置き換えてください。

検証

pnpm build
pnpm test
pnpm lint
pnpm smoke
pnpm run doctor
pnpm run healthcheck

手動確認:

curl http://127.0.0.1:8788/healthz
curl http://127.0.0.1:8788/readyz
curl -i -X PUT http://127.0.0.1:8788/mcp

Related MCP server: @prompthub/mcp

English

Overview

webgpt MCP is a local MCP server for sending prompts from Codex to ChatGPT Web Pro extension and returning the result to Codex.

This repository covers ChatGPT Web Pro extension automation and the .ai/tasks, .ai/results, .ai/reviews, and .ai/logs shared workbench.

The primary workflow is Codex-led. Codex gathers local repository context, optionally asks ChatGPT Web Pro extension for a higher-effort plan, captures the response, saves it locally, and then implements/verifies the change. ChatGPT Web does not need to call Codex directly.

Architecture

Codex CLI / IDE
  -> webgpt-mcp /mcp-codex
     -> run_pro_prompt
     -> Chrome / ChatGPT Web Pro extension
     <- Pro planning output
  -> registered local repositories
  -> .ai/pro-outputs
  -> .ai/tasks .ai/results .ai/reviews .ai/logs
  -> implementation and verification

Optional ChatGPT connector:
ChatGPT Web
  -> HTTPS tunnel
  -> webgpt-mcp /mcp
  -> safe planner/reviewer tools only

Requirements

• Node.js 20+

• pnpm

• macOS launchd is optional for production-style local daemon operation

• Cloudflare Tunnel is optional and only needed for a ChatGPT Web connector

Minimal Setup

No .env file is required. After cloning:

pnpm install
pnpm dev

The default server URL is http://127.0.0.1:8788. When you ask Codex to use webgpt, Codex should automatically register the current repository.

Use webgpt MCP.
Register the current repository automatically if needed, then call list_projects and repo_tree.

Registration automatically creates or updates projects.local.json in this MCP server working directory. You do not need to maintain an allowlist by hand. After registration, pass projectId to target a repository. When omitted, the default project is used.

{ "projectId": "my-project", "path": "package.json" }

The target repository gets these folders as needed:

.ai/tasks
.ai/results
.ai/reviews
.ai/logs
.ai/context

AGENTS.md is created only when missing. If it already exists, the server writes .ai/context/webgpt-workflow.md instead.

Optional Configuration

All MCP_* settings are optional. Add only what you need.

cp .env.example .env
chmod 600 .env

Common settings:

MCP_PORT=8788
MCP_PUBLIC_PIN=<short-lived-pin>
MCP_CODEX_TOKEN=<long-random-token>
MCP_ALLOWED_ORIGINS=https://chatgpt.com
MCP_PROJECTS_FILE=/absolute/path/to/projects.local.json
MCP_DEFAULT_PROJECT_ID=my-project

Set MCP_PUBLIC_PIN when exposing /mcp; every /mcp tool call then requires a pin argument.

Set MCP_CODEX_TOKEN when you want bearer auth on /mcp-codex. The minimal localhost-only path works without it.

Set MCP_PROJECTS_FILE only when you want to store the auto-generated registry somewhere else.

Codex Config

Automated setup:

pnpm run codex:configure

This works without .env or MCP_CODEX_TOKEN. If a token is available, it writes bearer_token_env_var into ~/.codex/config.toml.

Minimal config without token:

[mcp_servers.webgpt]
url = "http://127.0.0.1:8788/mcp-codex"
startup_timeout_sec = 20
tool_timeout_sec = 1200
enabled = true
default_tools_approval_mode = "prompt"

Config with token:

[mcp_servers.webgpt]
url = "http://127.0.0.1:8788/mcp-codex"
bearer_token_env_var = "MCP_CODEX_TOKEN"
startup_timeout_sec = 20
tool_timeout_sec = 1200
enabled = true
default_tools_approval_mode = "prompt"

Example Codex prompt:

Use webgpt MCP.
Automatically register the current repository if needed.
List projects.
List open tasks.
Pick the highest priority open task.
Read it.
Claim it.
Implement only that task.
Run available verification commands.
Run typecheck, lint, test, and build when available.
Write the result with write_result.
Do not edit unrelated files.
Do not skip verification.

Production Operation

For production-style local operation, run compiled JavaScript instead of tsx.

pnpm build
pnpm start

Before installing a daemon:

pnpm run doctor
pnpm run prod:verify

Install as a macOS LaunchAgent:

pnpm run launchd:install

Stop and remove it:

pnpm run launchd:uninstall

Check the service:

launchctl print "gui/$(id -u)/local.webgpt-mcp"
pnpm run healthcheck

Runtime logs:

.ai/logs/server.stdout.log
.ai/logs/server.stderr.log
.ai/logs/mcp-audit.jsonl

Endpoints

GET  /healthz
GET  /readyz
POST /mcp
GET  /mcp
POST /mcp-codex
GET  /mcp-codex

/mcp-codex is for Codex. If MCP_CODEX_TOKEN is set, bearer auth is required.

/mcp is for ChatGPT. You do not need it when the endpoint is not exposed. If you expose it, set MCP_PUBLIC_PIN and protect it with Cloudflare Tunnel or another access layer.

Tools

ChatGPT /mcp tools:

list_projects
repo_tree
read_file
grep_repo
git_diff
create_task
list_tasks
read_task
read_result
write_review

Codex /mcp-codex tools:

register_project
list_projects
pro_browser_status
prepare_pro_browser
run_pro_prompt
repo_tree
read_file
grep_repo
read_task
list_tasks
claim_task
write_result
read_result
git_diff
run_check

run_check only runs existing target-repository package.json scripts named typecheck, lint, test, or build. It never accepts arbitrary shell input.

MCP Inspector

npx @modelcontextprotocol/inspector@latest

Test endpoints:

http://127.0.0.1:8788/mcp
http://127.0.0.1:8788/mcp-codex

Checklist:

• list_projects succeeds

• register_project registers a target repository

• after registration, repo_tree, read_file, and grep_repo succeed

• create_task writes .ai/tasks/*.md

• claim_task and write_result write .ai/results/*.md

• run_check runs only allowlisted scripts

• when MCP_PUBLIC_PIN is set, a wrong PIN fails

• when MCP_CODEX_TOKEN is set, /mcp-codex without bearer auth returns 401

Cloudflare Tunnel

Only needed for a ChatGPT connector. It is not needed for localhost-only operation.

Quick tunnel:

pnpm dev
pnpm tunnel:quick

For a permanent tunnel, map a public hostname such as mcp.example.com to http://localhost:8788, then use https://mcp.example.com/mcp as the ChatGPT connector URL.

Connector steps:

1. Set MCP_PUBLIC_PIN.

2. Start the MCP server.

3. Start Cloudflare Tunnel.

4. Copy the generated HTTPS URL.

5. In ChatGPT, enable Developer mode.

6. Create a connector.

7. Set Connector URL to https://<cloudflare-tunnel-host>/mcp.

8. Enable the connector in a new chat.

9. Tell ChatGPT the short-lived MCP_PUBLIC_PIN for the session.

Codex to ChatGPT Pro Extension

Use this when Codex needs a higher-effort plan before implementation.

This is the core webgpt MCP feature. When Codex calls run_pro_prompt, the MCP server controls ChatGPT Web in Google Chrome, sends the prompt to Pro 拡張, waits for completion, saves the result under .ai/pro-outputs, and returns it to Codex.

Use pro_browser_status first when diagnosing failures. It reports the active backend, Chrome profile directory, and required permissions.

The default backend is playwright-chrome. Chrome 136+ ignores --remote-debugging-port for the default Chrome data directory, so the MCP defaults to a non-standard user-data-dir at ~/.webgpt-mcp/chrome-user-data and launches --profile-directory=webgpt inside it. This is not a separate Chrome app; it is a Chrome profile for MCP automation running in the normal Google Chrome app. If first-run login is required, call prepare_pro_browser, log into ChatGPT in the opened webgpt Chrome profile, then call run_pro_prompt.

Set MCP_PRO_USE_SYSTEM_CHROME_PROFILE=true only for explicit experiments with the normal Chrome profile root. It is not recommended on Chrome 136+ because CDP is ignored there. If polite quit is blocked and closing Chrome is acceptable, also pass forceChromeRestart: true. That sends SIGTERM to the Google Chrome app process, but never SIGKILL.

If you already run a logged-in Chrome with --remote-debugging-port, pass cdpEndpoint: "http://127.0.0.1:<port>" to run_pro_prompt / prepare_pro_browser, or set MCP_PRO_CDP_ENDPOINT in .env. The endpoint must be localhost-only.

MCP_PRO_BROWSER_MODE=chrome-applescript remains available for compatibility. Only this mode requires macOS Automation/Accessibility permission.

Use webgpt MCP.
Automatically register the current repository if needed.
Call pro_browser_status.
If login is required, call prepare_pro_browser and log into ChatGPT in the opened Chrome window.
Call run_pro_prompt with:
- title: "<short title>"
- modelLabel: "Pro 拡張"
- chromeProfileDirectory: "webgpt"
- allowChromeRestart: true
- forceChromeRestart: false
- timeoutSec: 1200
- keepBrowserOpen: true
- confirmSendToChatGpt: true
- prompt: |
  You are ChatGPT Pro extension. Your job is to create an implementation plan for Codex.

  Goal: <what Codex should implement>

  Output requirements:
  - Use the user's requested language
  - Provide 5 to 8 concrete implementation steps
  - Include security boundaries and failure handling
  - First line must be PRO_PLAN_START and last line must be PRO_PLAN_END
  - Do not include unnecessary preamble

Suggested output locations:

.ai/pro-outputs/PRO-YYYYMMDD-HHMMSS-<slug>.md
.codex/pro-plan/responses/<task_id>.md
docs/implementation/<task_id>/PRO_PLAN.md

Security

• The default is localhost-only minimal operation. If you do not expose endpoints, .env is not required.

• /mcp is safe by default: no shell, no patch application, no deletion, and no source writes.

• Set MCP_PUBLIC_PIN before exposing /mcp.

• Set MCP_CODEX_TOKEN before using /mcp-codex outside localhost.

• To mitigate DNS rebinding for Streamable HTTP, requests with an Origin header are accepted only when the origin is allowlisted.

• File paths are resolved under the registered repository. Path traversal and detectable symlink escapes are rejected.

• Denied reads include env files, secret/token paths, PEM/key files, .git, node_modules, build outputs, Next output, and coverage.

• Reads and diffs are byte-bounded and report truncation.

• Audit logs are JSON lines at .ai/logs/mcp-audit.jsonl.

• Pins, bearer tokens, and prompt bodies are not written to audit logs.

Production TODO: if you expose this outside localhost, replace the development PIN with OAuth 2.1 and/or a proper access layer such as Cloudflare Access, Auth0, or Stytch.

Verification

pnpm build
pnpm test
pnpm lint
pnpm smoke
pnpm run doctor
pnpm run healthcheck

Manual checks:

curl http://127.0.0.1:8788/healthz
curl http://127.0.0.1:8788/readyz
curl -i -X PUT http://127.0.0.1:8788/mcp