chatgpt-desktop-mcp
Integrates with the ChatGPT desktop app and Codex to list and read chats, create chats, send follow-ups, choose model/reasoning effort/speed, steer or interrupt running turns, and answer approval requests.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
chatgpt-desktop-mcp
An MCP server that lets other agents work with the Codex chats in the ChatGPT desktop app on your Mac: list and read conversations, start new chats in your projects, send follow-ups, pick the model, reasoning effort, and speed, steer or interrupt running work, and answer approvals. It runs locally and can be exposed to the internet behind bearer tokens, so a remote agent can monitor and drive your Codex work.
New chats open in the desktop app by default. You can type, steer, and interrupt them while they are running, without the “This is open in another app” lock.
Unofficial. Not affiliated with OpenAI. It combines the documented Codex app-server protocol with the desktop app's local IPC channel, which is internal and can change when the app updates. Run
chatgpt-desktop-mcp doctorafter updating the app.
How it works
flowchart LR
Agent["Remote agent or MCP client"] -->|"HTTPS + bearer token"| Tunnel["Tunnel or reverse proxy"]
Tunnel --> MCP["chatgpt-desktop-mcp\n127.0.0.1:8723/mcp"]
MCP -->|"local IPC (~/.codex/ipc)"| App["ChatGPT desktop app\nchats open in a window"]
MCP -->|"stdio JSON-RPC"| Engine["codex app-server\nbundled with ChatGPT.app"]
App --> Store[("~/.codex\nchats, projects, config")]
Engine --> StoreThe bridge routes each request to the right place:
New chats and follow-ups run through the desktop app by default. The bridge creates an empty chat, releases its writer lock, opens its
codex://threads/…link, and waits for the app to own it before sending the first prompt over local IPC. Stored chats are opened before sending a follow-up. Opening a chat changes the selected chat in the app window.Listing, history, and the model catalog use a private
codex app-serverwith the same~/.codexstorage. It does not run the default chat turns.Explicit headless runs use
execution: "background"oncreate_chatorsend_message. Chats already owned by the app continue to use its live controls. This mode remains useful when no desktop session is available.
Codex lets only one process write to a chat at a time. Default app execution keeps that owner inside the desktop app. Explicit background execution still locks its chats until the runner's last active turn finishes and the runner exits. A failed app handoff returns an error with the existing chat ID; it never silently starts a headless turn or retries a possibly delivered prompt.
Upgrading from 0.3: app is now the default execution mode. It uses the permissions selected in the desktop app. Explicit sandbox / approvalPolicy arguments or operator-enforced overrides require execution: "background" when creating a chat. create_chat returns deliveredVia and turnStarted; an app-started turn may have turnId: null, and wait: true still waits for it.
Related MCP server: web-gpt
Requirements
macOS with the ChatGPT desktop app and Codex. App execution needs a logged-in desktop session and an app-server supporting
thread/unsubscribeandthread_unload_delay_secs.Node.js 22 or newer.
Optional:
cloudflaredfor a public URL (brew install cloudflared). A fixed URL also needs a domain on Cloudflare.
Install
npm install -g https://github.com/kevinrss01/chatgpt-desktop-mcp/tarball/main
chatgpt-desktop-mcp doctorThe compiled CLI is committed in dist/, so installing from GitHub needs no build step. To pin a release, replace main with a tag such as v0.3.0. From a clone: npm install && npm link.
Quick start
# 1. Create a token. It is printed once; only its SHA-256 digest is stored.
chatgpt-desktop-mcp token create --name my-agent --scope control
# 2. Serve MCP on http://127.0.0.1:8723/mcp
chatgpt-desktop-mcp serve
# Or also publish it on a temporary public HTTPS URL
chatgpt-desktop-mcp serve --tunnelEvery request needs Authorization: Bearer <token>. Tokens have one of two scopes:
Scope | Tools |
|
|
| Everything in |
Manage tokens with chatgpt-desktop-mcp token list and chatgpt-desktop-mcp token revoke <id-or-name>.
Connect an agent
Claude Code
claude mcp add --transport http chatgpt-desktop https://YOUR-HOST/mcp --header "Authorization: Bearer $CDM_TOKEN"Codex CLI (~/.codex/config.toml)
[mcp_servers.chatgpt_desktop]
url = "https://YOUR-HOST/mcp"
bearer_token_env_var = "CDM_TOKEN"OpenAI Responses API
const response = await openai.responses.create({
model: 'gpt-6.1-sol',
input: 'Check my Codex chats and summarize what is still running.',
tools: [
{
type: 'mcp',
server_label: 'chatgpt_desktop',
server_url: 'https://YOUR-HOST/mcp',
headers: { Authorization: `Bearer ${process.env.CDM_TOKEN}` },
require_approval: 'never',
},
],
});Local stdio clients (no token; the client launches the server):
{ "mcpServers": { "chatgpt-desktop": { "command": "chatgpt-desktop-mcp", "args": ["stdio"] } } }Add "--read-only" to the args for a monitoring-only setup. ChatGPT custom connectors require OAuth, which this server does not implement yet.
To try tools from a terminal: CDM_URL=http://127.0.0.1:8723/mcp CDM_TOKEN=... node scripts/call-tool.mjs list_chats '{"limit":5}'.
Tools
Tool | What it does |
| The Macs this endpoint can reach, whether each is available, and its access level. See Several Macs. |
| Models available to the app with their reasoning efforts and speed tiers. |
| Projects saved in the app, plus folders used by recent chats. |
| Chats sorted by last activity; filter by project, search text, or archived state. |
| The latest turns of a chat in order: messages, plus one-line summaries of commands, edits, and tool calls. Page back with |
| Whether the chat is running and where ( |
| Waits until the chat stops running (up to 300 s), then returns its status. |
| Starts a chat in a project (or a new folder under |
| Sends a follow-up. If the chat is busy, |
| Stops the running turn. |
| Retitle, archive, or restore a chat. |
| See and answer command, file, question, and MCP approval requests from chats the bridge runs. |
Model, effort, and speed. list_models returns valid values. speed accepts standard, a tier id such as priority or ultrafast, or a tier name such as Fast. For a chat open in the app, a model or effort change is applied for the next turn, as the app's model picker does.
A typical monitoring loop: list_chats to see what changed, get_chat_status for live state, wait_for_chat until a run ends, then read_chat for the transcript.
Exposing it safely
A control token lets the holder make Codex run commands on your Mac with the permissions in your Codex configuration. Treat it like SSH access.
The server listens on
127.0.0.1by default. Publish it through a TLS tunnel or reverse proxy; do not bind it to a public interface.serve --tunnelstarts a Cloudflare quick tunnel. Its URL is random and changes on every start, which suits testing. For a fixed address on your own domain, useservice installbelow.Give monitoring agents
readtokens. Revoke tokens you no longer use.Requests carrying a browser
Originheader are rejected unless allowed with--allow-origin, which also enables CORS for that origin. Repeated failed authentication from one client returns 429.To restrict chats the bridge starts or resumes, run with
--sandbox workspace-write --approval-policy on-requestand answer approvals withrespond_to_request. Callers cannot loosen these settings through tool arguments. Chats open in the app keep the app's own settings.
Keep it running on your own URL
service install keeps the server running in the background with macOS LaunchAgents. It starts at login, restarts after a crash, and a watchdog checks it every two minutes. Choose how other agents reach it:
Setup | Command | What you need |
Your own domain through Cloudflare (recommended) |
| A domain on Cloudflare (the free plan works) and |
Your own tunnel or proxy |
| Tailscale Funnel, ngrok, Caddy, nginx, or anything that forwards HTTPS to |
This Mac only |
| Nothing else; local clients use |
Then create a token for each agent with chatgpt-desktop-mcp token create --name <agent> and check everything with chatgpt-desktop-mcp service status.
Your own domain through Cloudflare
brew install cloudflared
cloudflared tunnel login # pick the domain that will hold the hostname
chatgpt-desktop-mcp service install --hostname mcp.yourdomain.com
chatgpt-desktop-mcp token create --name my-agentAgents connect to https://mcp.yourdomain.com/mcp. Install creates a named tunnel in your Cloudflare account (chatgpt-desktop-mcp unless you pass --tunnel-name), adds a DNS record for the hostname, and forwards only that hostname to the local server. It stops before touching DNS if the domain does not use Cloudflare nameservers, and it never replaces an existing record unless you pass --overwrite-dns.
The certificate from cloudflared tunnel login covers one domain. If you have several, log in again for the domain you want or set TUNNEL_ORIGIN_CERT=/path/to/cert.pem before running install.
Your own tunnel or proxy
Run your tunnel so it forwards to http://127.0.0.1:8723, then tell the service its URL. With Tailscale Funnel, for example:
tailscale funnel --bg 8723
chatgpt-desktop-mcp service install --public-url https://my-mac.your-tailnet.ts.netThe service keeps the MCP server running and checks the public URL, so service status shows when it is down. Keeping the tunnel or proxy itself running is up to that tool.
Options
Install saves its settings in ~/.config/chatgpt-desktop-mcp/service.json. Running service install again, for example after upgrading Node or this package, reuses them; any option you pass replaces the saved value.
Option | Default | Effect |
| none | Publish on your domain through a named Cloudflare tunnel. |
|
| Cloudflare tunnel to create or reuse. |
| none | Run a tunnel created on another Mac; see A second Mac. |
| off | Replace an existing DNS record for the hostname. |
| off | Skip the check that the domain uses Cloudflare DNS. |
| none | Use a tunnel or proxy you run yourself. The service monitors it. |
| Remove the saved hostname or public URL. | |
|
| Local port. |
|
|
|
| open | Open the ChatGPT app in the background at login. |
| your Codex settings | Passed to the background server, as with |
| Ignore the saved settings and start from the defaults. |
If you set CHATGPT_DESKTOP_MCP_CONFIG_DIR, CODEX_HOME, or CHATGPT_DESKTOP_MCP_CODEX_BIN when running install, the background agents use the same values. Each macOS user can run one service.
What runs in the background
LaunchAgents live in ~/Library/LaunchAgents and write logs to ~/Library/Logs/chatgpt-desktop-mcp:
Agent | What it does |
| Runs |
| With |
| Every 2 minutes, restarts the server if |
| Runs |
| Opens the ChatGPT app in the background at login so open chats can be controlled live. |
service uninstall removes the agents and keeps the Cloudflare tunnel and DNS record; delete those with cloudflared tunnel delete <name> and the Cloudflare dashboard.
macOS folder permissions
macOS asks before a background process reads Documents, Desktop, Downloads, iCloud Drive, or external drives. New chats go in ~/Documents/Codex by default, and your projects may live in those folders, so the background server checks access when it starts and macOS shows a prompt for node. Click Allow. To cover every folder at once, add the node binary shown by service status to System Settings › Privacy & Security › Full Disk Access. Upgrading Node can reset this permission.
service status reports whether the server can read the chat folder. Install the package itself outside those folders, as a global npm install does; a copy inside Documents cannot start in the background until node is allowed there.
What it survives
Network drops and Wi‑Fi changes: the tunnel reconnects and the URL does not change.
Crashes and hangs: launchd restarts the server and tunnel within about 10 seconds, and the watchdog restarts a process that stops answering.
Restart or shutdown: everything starts again once you log in. With FileVault on, macOS waits for your password at boot, so the URL is down until then. To power back on after a power cut, run
sudo pmset -a autorestart 1.Sleep: a sleeping Mac cannot answer.
--keep-awakeprevents idle sleep; on battery only withalways.Closing the lid: the Mac sleeps unless it is in clamshell mode (power plus an external display).
sudo pmset -a disablesleep 1keeps it awake with the lid closed; undo withsudo pmset -a disablesleep 0. A closed, awake laptop runs warm, so do not put it in a bag.The ChatGPT app: listing, reading, and new chats work without it. Live control of chats open in a window needs the app running.
For an address that stays up while your laptop is off, run the bridge on an always-on Mac, such as a Mac mini, and point your agents there.
Several Macs behind one endpoint
Run the bridge on each Mac, then register the other Macs on the one your agents connect to. Every tool gains a machine argument, and list_machines shows which Macs are reachable, so an agent can pick where to start a chat or follow one on any machine.
# On the Mac mini: run the service and create a token for the endpoint that will reach it
chatgpt-desktop-mcp service install --hostname mini-mcp.example.com
chatgpt-desktop-mcp token create --name laptop-endpoint
# On the Mac your agents connect to
chatgpt-desktop-mcp machine name laptop
chatgpt-desktop-mcp machine add mini --url https://mini-mcp.example.com/mcp # paste the token at the prompt
chatgpt-desktop-mcp machine listlaptop available this Mac, control access, ChatGPT app open, v0.3.0
mini available https://mini-mcp.example.com/mcp, control access, ChatGPT app closed, v0.3.0, 180 msAgents then pass machine to any tool:
Value | Runs on |
omitted, | The Mac serving the endpoint |
a name such as | That Mac |
| The first available Mac in the order shown by |
| Every Mac, for |
Results from a routed call include machine, so the agent knows where a chat lives. list_machines reports, for each Mac, whether it answers, whether the endpoint can control it or only read it, its version, and whether its ChatGPT app is open for live control.
Machines are managed only from the command line, never through MCP. Tokens for other Macs are stored in ~/.config/chatgpt-desktop-mcp/machines.json with owner-only permissions. A few ways to limit what the endpoint can do:
Give it a
readtoken from the other Mac, or add the Mac with--read-only. Only read tools are forwarded to it.Agents holding a
readtoken on the endpoint can only read, on every Mac.To make both Macs entry points, register each on the other. Forwarded calls always run on the receiving Mac, so they never loop.
A second Mac without a Cloudflare login
A tunnel can run on a Mac that is not logged in to Cloudflare. Create it on a Mac that is, then copy its credentials file:
# On the Mac logged in to Cloudflare
cloudflared tunnel create mini-mcp
cloudflared tunnel route dns mini-mcp mini-mcp.example.com
# copy ~/.cloudflared/<tunnel-id>.json to the other Mac, then on that Mac:
chatgpt-desktop-mcp service install --hostname mini-mcp.example.com --tunnel-credentials ./<tunnel-id>.jsonInstall copies the file into the config folder, so you can delete the copy you transferred.
Limitations
macOS only. Live control relies on the app's internal IPC messages and may need an update after a ChatGPT release. Use explicit background execution if desktop control is unavailable.
When a chat is not open in the app, the router can take about 10 seconds to confirm that before the bridge opens it. A new-chat handoff waits up to 30 seconds for the desktop app to take ownership.
Explicit background turns still prevent desktop input until the runner releases them. Existing background turns are not moved or interrupted by an app handoff for another chat.
Renaming or archiving a chat that the app currently has loaded is refused; do it in the app.
Approvals for runs inside the app are answered in the app;
get_chat_statusshows that one is waiting.Messages are text only. Regular ChatGPT conversations outside Codex are stored in your ChatGPT account, not in
~/.codex, and are not covered.
Development
npm install
npm test # unit and protocol tests (no app needed)
npm run build # rebuild dist/ and commit it with your change
node dist/cli.js serve --verboseThe tests cover machine routing between two in-process servers, the IPC framing and a fake desktop router, token storage, model option resolution, history formatting, live-state parsing, and HTTP authentication and scopes through a real MCP client.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Substack MCP server for ChatGPT, Claude and any AI agent: create post, schedule post, publish Note, reply to Notes, send direct message, moderate comments, list subscribers and get post stats in your own Substack account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Substack yourself; Cotlet does not store your password and you need no Substack API key. About the official Substack API: Substack has only a limited API (checked 11 Oct 2026). Its Developer API looks up public creator profiles after approval, and there is no public API to write posts or Notes, manage subscribers or send email. Setup and FAQ: https://cotlet.dev/integrations/substack-api-mcp-server
Fathom MCP server for ChatGPT, Claude and any AI agent: list calls, complete action item, add action item, share call, set link access, regenerate summary, update settings and delete call in your own Fathom account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Fathom yourself; Cotlet does not store your password and you need no Fathom API key. About the official Fathom API: Fathom has a REST API and an official MCP server, but both only read your calls (checked 22 Oct 2026). The API lists meetings and returns summaries, transcripts and action items, requests recording downloads and manages webhooks. Setup and FAQ: https://cotlet.dev/integrations/fathom-video-api-mcp-server
Chatwoot MCP server for ChatGPT, Claude and any AI agent: list conversations, reply to conversation, add private note, assign conversation, add labels and resolve or snooze conversation in your own Chatwoot account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Chatwoot yourself; Cotlet does not store your password and you need no Chatwoot API key. About the official Chatwoot API: Chatwoot has a full REST API, the Application API, and an official command-line client, but no official MCP server (checked 22 Oct 2026). The API covers conversations, messages, contacts, labels, teams and assignments with an access token from Profile Settings. Setup and FAQ: https://cotlet.dev/integrations/chatwoot-api-mcp-server
Peerspace MCP server for ChatGPT, Claude and any AI agent: list booking requests, reply to inquiry, send custom proposal, accept booking and update listing pricing in your own Peerspace account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Peerspace yourself; Cotlet does not store your password and you need no Peerspace API key. About the official Peerspace API: Peerspace has no public API, developer portal or webhooks for hosts (checked 11 Oct 2026). The only built-in connection is calendar sync through iCal links or Cronofy, which keeps your availability accurate and nothing more. Setup and FAQ: https://cotlet.dev/integrations/peerspace-api-mcp-server
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLocal macOS MCP bridge that gives ChatGPT shell, unrestricted filesystem access, real PTY sessions, background jobs, and read-only stored Codex history. ChatGPT stays the reasoning layer; the bridge makes no model calls.57MIT
- AlicenseAqualityCmaintenanceEnables Codex to send text tasks to ChatGPT web, await responses, continue conversations, choose reasoning effort, and manage projects through MCP tools on macOS.2MIT
- AlicenseNot gradedqualityBmaintenanceA local MCP bridge that lets ChatGPT chat mode operate the user's own computer, running project, file, and shell tasks through a local executor and returning progress and results to the conversation. It also coordinates Codex sessions (persistent or one-off) and other agent CLIs as sub-agents.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables ChatGPT to operate a local workstation through a secure outbound tunnel, exposing 44 MCP tools for files, git, projects, processes, browsers, native apps, Office documents, and optional Codex delegation across macOS, Linux, and Windows.1MIT