codex-chats-mcp
An MCP server for managing ChatGPT conversations and Codex Cloud tasks (chats) from any MCP-compatible client — Claude Code, Codex, Cline, etc.
ChatGPT's web UI lets you archive chats but the "Delete all" button only wipes visible ones, and Codex Cloud has no per-task delete at all. This server wraps the internal chatgpt.com/backend-api endpoints so you can list, search, rename, archive, export, and permanently delete both kinds of chats from your agent.
Unofficial. This uses undocumented internal endpoints (
/conversations/*,/wham/tasks/*). They can change without notice and require a valid ChatGPT session. Use at your own risk.
Install
pip install codex-chats-mcp
Or with uv:
uv tool install codex-chats-mcp
This installs a codex-chats-mcp executable.
Authentication
The server reads ~/.codex/auth.json — the same file the Codex CLI maintains after codex login. If you don't have Codex installed, log in once with npx @openai/codex login (or sign in via the Codex desktop app) to produce the file.
The token has full access to your ChatGPT account. Treat the auth file as a secret.
Wire it up
Codex CLI (~/.codex/config.toml)
[mcp_servers.codex-chats]
command = "codex-chats-mcp"
Claude Code
claude mcp add codex-chats codex-chats-mcp
Anything else
Point your MCP client at the codex-chats-mcp executable. It speaks MCP over stdio.
Tools
ChatGPT conversations (the "Recents" list)
| Tool | What it does |
|---|---|
list_conversations |
Paginates through your conversations. Filters out archived by default. |
get_conversation |
Full payload for one conversation, including the message tree. |
search_conversations |
Substring match on titles (client-side). |
rename_conversation |
Change a conversation's title. |
archive_conversation / unarchive_conversation |
Toggle the archive flag. |
delete_conversation |
Permanently delete one chat (is_visible=false). No undo. |
delete_conversations_matching |
Delete every chat whose title matches a substring. Requires confirm=True. |
delete_all_conversations |
Nuke every visible chat — same as ChatGPT's "Delete all chats" button. Requires confirm=True. |
export_conversations |
Dump titles/IDs (and optionally full message trees) to a JSON file. |
Codex Cloud tasks
| Tool | What it does |
|---|---|
list_chats |
Paginate Codex tasks, filterable by all / current / archived. |
get_chat |
Summary of one task. |
get_chat_raw |
Full raw task payload. |
archive_chat / unarchive_chat |
Toggle archive state. |
delete_chat |
Permanently delete a task. Works on active OR archived. |
delete_all_archived |
Bulk-delete every archived task. Requires confirm=True. |
Safety
Every destructive bulk action (delete_all_conversations, delete_all_archived, delete_conversations_matching) requires confirm=True. Without it the tool returns a preview of what would be deleted. There is no undo on the ChatGPT side.
Development
git clone https://github.com/shoyu-ramen/codex-chats-mcp
cd codex-chats-mcp
python3 codex_chats_mcp.py
License
MIT
