read-my-chatgpt

# Read My ChatGPT [](https://github.com/Async23/read-my-chatgpt/actions/workflows/ci.yml) [](https://github.com/Async23/read-my-chatgpt/actions/workflows/codeql.yml) [](https://www.npmjs.com/package/read-my-chatgpt) [](LICENSE) Provide your own ChatGPT Web session history to multiple AI clients on your machine as a read-only MCP tool. A single background MCP server shares an Obscura browser process, without launching duplicates for each client. > [!WARNING] > This project uses ChatGPT's non-public Web endpoint, not an official OpenAI product, and is not endorsed or sponsored by OpenAI. OpenAI's terms of use restrict automated or programmatic data extraction or output; please ensure your use case is permitted and assume account and compliance risks. ## Get Started in Two Commands Requires Node.js 22 or higher. One-click background service supported: | OS | CPU | Requirements | |---|---|---| | macOS | arm64, x64 | launchd | | Linux | arm64, x64 | systemd user, glibc 2.35+ | Windows, Alpine/musl not supported for one-click background service; still use stdio mode. ```bash npm install -g read-my-chatgpt read-my-chatgpt setup ``` `setup` will: 1. Prompt for your ChatGPT Web access token; 2. Download a fixed version of Obscura (`v0.1.10`) from the official GitHub Release and verify SHA-256; 3. Generate a local MCP Bearer token, written to a `0600` permission config file; 4. Install a launchd (macOS) or systemd user (Linux) background service; 5. Automatically configure detected Codex, Claude Code, Cursor, Gemini CLI, Grok CLI, OpenCode, and Pi. First run will prompt to confirm risks. Automated installation requires explicit environment variable setting and confirmation: ```bash READ_MY_CHATGPT_ACCESS_TOKEN='…' read-my-chatgpt setup --yes ``` Restart AI clients after setup. They will connect to: ```text http://127.0.0.1:47831/mcp ``` The service only allows loopback, not listening on LAN or public networks. ## Migrate from Old Package If previously installed `conversation-reader-mcp`: ```bash npm install -g read-my-chatgpt read-my-chatgpt setup --yes npm uninstall -g conversation-reader-mcp ``` `setup` will stop the old background service, migrate existing token, Obscura, browser profile, and logs to `read-my-chatgpt` path, and replace `conversation-reader` entries in AI clients with `read-my-chatgpt`. Normal migration does not require re-entering the token. ## Obtain Access Token 1. Log in to [chatgpt.com](https://chatgpt.com/); 2. Open Network in Developer Tools; 3. Find any `/backend-api/*` request; 4. Copy the `Authorization: Bearer …` value. Tokens expire. When expired, re-run `read-my-chatgpt setup` to input a new token; the background service and client configurations will update together. Do not submit tokens to Git, Issues, logs, or chat messages. ## Daily Commands ```bash # Check Node, config permissions, Obscura, background service, and HTTP endpoint read-my-chatgpt doctor # Output diagnostic results in JSON for script reading (no tokens) read-my-chatgpt doctor --json # Reconfigure detected clients read-my-chatgpt configure # Specify clients; also use 'all' to create all 7 configurations read-my-chatgpt configure codex cursor gemini read-my-chatgpt configure all # Stop service and remove MCP entries from clients; preserves token and browser profile by default read-my-chatgpt uninstall # Also delete project-saved config, token, Obscura, and profile read-my-chatgpt uninstall --purge ``` Client configurations are backed up with `.bak` before modification; if `.bak` exists, a new backup with a timestamp is created. Since client configurations include MCP Bearer tokens, modified files and backups are set to `0600`. ## Supported Clients | Client | Default Config File | Format | |---|---|---| | Codex | `~/.codex/config.toml` | Streamable HTTP `url` + `http_headers` | | Claude Code | `~/.claude.json` | `type: "http"` + `url` + `headers` | | Cursor | `~/.cursor/mcp.json` | `url` + `headers` | | Gemini CLI | `~/.gemini/settings.json` | `httpUrl` + `headers` | | Grok CLI | `~/.grok/config.toml` | `url` + `headers` | | OpenCode | `~/.config/opencode/opencode.json` | `type: "remote"` | | Pi | `~/.pi/agent/mcp.json` | `pi-mcp-adapter` remote config | Pi does not have built-in MCP; execute `pi install npm:pi-mcp-adapter` first. `setup` will automatically write Pi configuration after detecting the adapter. Other MCP clients supporting Streamable HTTP can be used manually: ```json { "url": "http://127.0.0.1:47831/mcp", "headers": { "Authorization": "Bearer <value generated in service.json>" } } ``` The Bearer token is saved in `~/.config/read-my-chatgpt/service.json`. Do not share this file; share the npm package or GitHub repository, not your local configuration. ## MCP Tools | Tool | Purpose | |---|---| | `list_conversations` | Paginate and list Chat/Work session metadata and `experience` | | `get_conversation` | Read visible text and structured links, citations, Mermaid, image/attachment indexes of the current active branch | | `get_asset` | Read image or regular attachment body using `asset_id` returned by `get_conversation` | | `search_conversations` | Search by title substring and return `experience` | `get_conversation` preserves the original `messages[].content` text field; only adds `messages[].rich_content` when messages contain rich content: ```json { "links": [{ "kind": "web", "url": "https://…", "title": "…" }], "citations": [{ "url": "https://…", "title": "…", "reference_type": "sources_footnote" }], "diagrams": [{ "format": "mermaid", "source": "graph TD\n A --> B" }], "assets": [{ "asset_id": "asset_…", "kind": "image", "name": "chart.png", "mime_type": "image/png", "size_bytes": 1234, "width": 1024, "height": 768 }] } ``` Reading images/attachments requires passing the same `conversation_id` and `asset_id` to `get_asset`. Images are returned as MCP `image` content; other files are returned as MCP embedded `resource` with Base64 blob. The default asset size limit is 10 MiB; adjust with `READ_MY_CHATGPT_MAX_ASSET_BYTES` (up to 32 MiB). Limitations: - Read-only, no sending, modifying, archiving, or sharing sessions; - Reads live Web data, no local session archiving; - Supports reading completed cloud Work sessions; returns `experience` and `completion_status`, hides internal reasoning, sub-agent events, and tool executions; - Supports images and regular file attachments directly referenced by current visible messages; - Does not track running Work or reproduce Canvas/HTML/React previews, Apps cards, Work Sites, Google Docs/Sheets/Slides, or other interactive runtime; - `search_conversations` only searches titles; - Only handles personal accounts, no Team/Workspace headers; - Tokens expire and require manual update. ## Architecture ```text Codex / Claude / Cursor / Gemini / Grok / OpenCode / Pi │ Streamable HTTP + Bearer │ 127.0.0.1:47831/mcp │ 1 Node MCP singleton │ 1 Obscura sidecar │ chatgpt.com/backend-api (read-only whitelist) ``` Each client has an independent MCP session but shares the same upstream browser runtime. ChatGPT access token is injected into the page via local CDP XHR, not passed to Obscura argv or logs. Allowed upstream endpoints: ```text GET /backend-api/conversations GET /backend-api/conversation/{id} GET /backend-api/files/download/{file_id}?conversation_id={id}&inline=false ``` The last endpoint only provides a one-time download link for `asset_id` that has appeared in the current visible branch of the session. Subsequently, only HTTPS asset URLs returned by the upstream are accessed; existing access tokens are only carried when same-origin with the configured ChatGPT `baseUrl`; cross-domain downloads never carry tokens. Signed URLs do not appear in MCP return values or error messages. Size limits and MIME checks are performed before and after downloads; HTML responses and "image returns non-image MIME" are rejected. ## Privacy and Local Files Default locations: ```text ~/.config/read-my-chatgpt/service.json ~/.local/share/read-my-chatgpt/obscura/ ~/.local/share/read-my-chatgpt/obscura-profile/ ``` `service.json` contains access tokens and MCP Bearer tokens; `obscura-profile/` may contain cookies and localStorage, both of which should be protected as account-sensitive data. The project does not provide cloud relay or telemetry upload of these data. macOS logs are located at `~/Library/Logs/read-my-chatgpt{,.error}.log`. Linux uses: ```bash journalctl --user -u read-my-chatgpt.service ``` ## Stdio Compatibility Old clients can launch CLI directly; this mode does not provide "full-client singleton": ```bash export READ_MY_CHATGPT_ACCESS_TOKEN='…' read-my-chatgpt ``` The first launch still downloads and verifies Obscura. Specify an existing compatible version: ```bash export READ_MY_CHATGPT_OBSCURA_BIN='/absolute/path/to/obscura' ``` ## Development from Source ```bash git clone https://github.com/Async23/read-my-chatgpt.git cd read-my-chatgpt npm ci npm run check ``` For real account debugging: ```bash export READ_MY_CHATGPT_ACCESS_TOKEN='…' npm run smoke npm run smoke:stability ``` ## Security and Dependencies - Report security issues privately per [SECURITY.md](SECURITY.md). - Obscura is downloaded separately from its official Release during the first setup, not included in the npm tarball; version, verification value, and license information see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). - OpenAI terms of use and brand guidelines may change; refer to [Terms of Use](https://openai.com/policies/terms-of-use/) and [Brand guidelines](https://openai.com/brand/). ## Participation and Support - Usage issues and desensitization requirements: [SUPPORT.md](SUPPORT.md) - Contribution process and local checks: [CONTRIBUTING.md](CONTRIBUTING.md) - Private security vulnerability reporting: [SECURITY.md](SECURITY.md) - Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - Version changes: [CHANGELOG.md](CHANGELOG.md) ## License [MIT](LICENSE)