ChatGPT Context MCP

中文文档

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.

Related MCP server: ChatCrystal

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:

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

git clone https://github.com/OWNER/chatgpt-context-mcp.git
cd chatgpt-context-mcp
npm install
npm run build

Run checks:

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:

export CHATGPT_BEARER_TOKEN="<chatgpt-bearer-token>"
export CHATGPT_ACCOUNT_ID=""

For desktop apps, use the wrapper script with a private fallback env file:

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:

[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:

[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:

{
  "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:

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:

$HOME/.cache/chatgpt-context-mcp/

Override the cache location:

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

npm install
npm test
npm run typecheck
npm run build
npm run check

Run the server locally:

npm run start:mcp

License

MIT