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 git+https://github.com/shoyu-ramen/codex-chats-mcp
Or with uv:
uv tool install git+https://github.com/shoyu-ramen/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
1 maintainer
Metadata
1 maintainer
Release files for codex-chats-mcp 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| codex_chats_mcp-0.1.1.tar.gz | 7.4 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| codex_chats_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 15.3 kB
Release files / codex_chats_mcp-0.1.1.tar.gz
| Download URL | codex_chats_mcp-0.1.1.tar.gz |
|---|---|
| Size | 7.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2fdf87e802d69a965282a0c1ad7c7b28fc7466fc1de2c1a7353b0aee5123250f
|
|
BLAKE2b-256 checksum How to use checksums |
34cd69cf9748c9c03ebde3c1b80c94e7ce54f9f5ed82700d8442d61844324c13
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 21, 2026.
Transparency logRelease files / codex_chats_mcp-0.1.1-py3-none-any.whl
| Download URL | codex_chats_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 7.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
70c153c621da5e3cafcf3a76cdcc03b8c5fb39d2455451cecb0b22864098727a
|
|
BLAKE2b-256 checksum How to use checksums |
76c019d25182ce20f6703c19e681ed743abb6216eec68f7e8b1c2c6aea5141cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 21, 2026.
Transparency logSecurity for codex-chats-mcp 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for codex_chats_mcp-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
