Codex Chats

PyPI version Python versions License: MIT Publish to PyPI

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