Content
# ChatGPT Context MCP
[中文文档](./README.zh-CN.md)
A local stdio MCP server for importing private ChatGPT conversation context into Codex, Claude Code, and other MCP clients.
## Disclaimer
This is an unofficial project. It is not maintained, endorsed, or supported by OpenAI.
This tool uses private, non-public ChatGPT web backend APIs. The behavior was inferred from web traffic and may change, break, or return incomplete data at any time. This project is provided only for technical research, personal context migration, and local MCP experimentation.
No guarantees are made about correctness, reliability, stability, completeness, legality, compliance, or fitness for any purpose. You are responsible for your own use, including token handling, data privacy, local laws, organization policy, and relevant service terms. Bearer tokens are sensitive temporary credentials and should be handled like passwords. Use at your own risk.
## Features
- Imports private ChatGPT conversation URLs into MCP clients.
- Refreshes remote conversation content by default before returning context.
- Caches JSON, Markdown, messages, and metadata locally.
- Supports cache-only reads for previously imported conversations.
- Provides MCP tools and cache-backed resources.
- Documents setup for Codex and Claude Code.
## Supported Scope
Supported:
```text
https://chatgpt.com/c/{conversation_id}
https://chat.openai.com/c/{conversation_id}
```
Not supported:
- Shared links such as `https://chatgpt.com/share/{share_id}`
- ChatGPT Projects
- Bulk history export
- Attachment, image, or Canvas downloads
- Browser automation or cookie extraction
## How It Works
`import_chatgpt_url` parses a private ChatGPT conversation URL, fetches the full remote conversation through ChatGPT's web backend API, compares a stable content hash with local metadata, updates the cache when content changed, and returns bounded Markdown/messages/JSON to the MCP client.
`get_chatgpt_context` reads local cache only. It does not check the remote conversation.
## Install From Source
Requirements:
- Node.js 20+
- npm
```bash
git clone https://github.com/OWNER/chatgpt-context-mcp.git
cd chatgpt-context-mcp
npm install
npm run build
```
Run checks:
```bash
npm run check
```
## Token Setup
Get a fresh ChatGPT web bearer token from your browser DevTools. Do not paste tokens into agent chat or commit them to config files.
You can provide credentials through the current process environment:
```bash
export CHATGPT_BEARER_TOKEN="<chatgpt-bearer-token>"
export CHATGPT_ACCOUNT_ID=""
```
For desktop apps, use the wrapper script with a private fallback env file:
```bash
mkdir -p "$HOME/.config/chatgpt-context-mcp"
chmod 700 "$HOME/.config/chatgpt-context-mcp"
cat > "$HOME/.config/chatgpt-context-mcp/env" <<'EOF'
export CHATGPT_BEARER_TOKEN="<chatgpt-bearer-token>"
export CHATGPT_ACCOUNT_ID=""
EOF
chmod 600 "$HOME/.config/chatgpt-context-mcp/env"
```
The wrapper uses this precedence:
1. Existing process environment variables.
2. Values from `$HOME/.config/chatgpt-context-mcp/env`.
Set `CHATGPT_CODEX_MCP_ENV_FILE` to point at a different env file.
## Codex Configuration
Built mode:
```toml
[mcp_servers.chatgpt_context]
command = "<repo-path>/scripts/start-mcp.sh"
args = []
env_vars = ["CHATGPT_BEARER_TOKEN", "CHATGPT_ACCOUNT_ID", "CHATGPT_CODEX_MCP_CACHE_DIR", "CHATGPT_CODEX_MCP_ENV_FILE"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "auto"
```
Development mode:
```toml
[mcp_servers.chatgpt_context]
command = "npm"
args = ["run", "start:mcp", "--prefix", "<repo-path>"]
env_vars = ["CHATGPT_BEARER_TOKEN", "CHATGPT_ACCOUNT_ID", "CHATGPT_CODEX_MCP_CACHE_DIR"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "auto"
```
Restart Codex or open a new session after changing MCP configuration.
## Claude Code Configuration
Configure this as a stdio MCP server:
```json
{
"mcpServers": {
"chatgpt_context": {
"command": "<repo-path>/scripts/start-mcp.sh",
"args": [],
"env": {
"CHATGPT_CODEX_MCP_ENV_FILE": "$HOME/.config/chatgpt-context-mcp/env"
}
}
}
}
```
Client-specific UI and config locations may vary. The server itself is a standard stdio MCP server.
## MCP Tools
- `import_chatgpt_url`: Fetches a private ChatGPT conversation URL from the remote API by default, updates cache when content changed, and returns bounded context.
- `get_chatgpt_context`: Reads a cached conversation. Does not access the network.
- `list_chatgpt_imports`: Lists locally cached imports.
- `verify_chatgpt_auth`: Checks token presence, expiration, account id detection, and lightweight API access.
## MCP Resources
Cache-backed resources:
```text
chatgpt://conversation/{conversation_id}/metadata
chatgpt://conversation/{conversation_id}/markdown
chatgpt://conversation/{conversation_id}/messages
chatgpt://conversation/{conversation_id}/json
```
Resource reads are cache-only and do not refresh remote content.
## Cache and Privacy
Imported conversations are cached as plaintext under:
```text
$HOME/.cache/chatgpt-context-mcp/
```
Override the cache location:
```bash
export CHATGPT_CODEX_MCP_CACHE_DIR="/path/to/cache"
```
Cache files may contain private prompts, assistant replies, code, and other sensitive content. The server does not write bearer tokens to disk.
## Troubleshooting
If `verify_chatgpt_auth` fails:
- Confirm `CHATGPT_BEARER_TOKEN` is available to the MCP server.
- Refresh the bearer token if it expired.
- For Team or Enterprise accounts, set `CHATGPT_ACCOUNT_ID` if auto-detection fails.
- Restart the MCP client after changing config or environment variables.
If `import_chatgpt_url` returns `UNSUPPORTED_URL`, use a private `/c/{conversation_id}` URL rather than a `/share/{share_id}` URL.
If remote access fails but cache exists, the error includes `cache_available: true`. Use `get_chatgpt_context` only when stale cached context is acceptable.
## Development
```bash
npm install
npm test
npm run typecheck
npm run build
npm run check
```
Run the server locally:
```bash
npm run start:mcp
```
## License
MIT
