Skip to main content
Glama
shoyu-ramen

codex-chats-mcp

by shoyu-ramen
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

codex-chats-mcp

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.

Related MCP server: Read My ChatGPT

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Read My ChatGPT

    Async23
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides a read-only MCP server to access ChatGPT conversation history via a local browser process. Allows AI clients to list, get, and search conversations from the authenticated user's ChatGPT account.
    44 npm
    MIT

  • chist

    hiropon164
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server for unified full-text search across chat histories from Claude Code, Codex, Cursor CLI, and Antigravity CLI, using SQLite FTS5. Provides read-only tools to search sessions, list conversations, and retrieve session details.
    MIT