chatgpt-context-mcp: Instructions file for Codex

Agent Guide

This file is for Codex, Claude Code, and other coding agents working in this repository.

Project Summary

chatgpt-context-mcp is a local stdio MCP server that imports private ChatGPT conversation context into MCP clients.

Supported URLs:

https://chatgpt.com/c/{conversation_id}
https://chat.openai.com/c/{conversation_id}

Do not add support for shared links, ChatGPT Projects, bulk export, attachment downloads, or browser automation unless the user explicitly asks for a new design and approves it.

Required Commands

Before finishing changes, run:

npm test
npm run typecheck
npm run build

For release-readiness checks, run:

npm run check

Local MCP Setup

Build first:

npm install
npm run build

The built server entrypoint is:

<repo-path>/dist/src/server.js

The recommended startup command for desktop MCP clients is:

<repo-path>/scripts/start-mcp.sh

The wrapper uses this precedence:

1. Existing process environment variables.
2. Fallback values from $HOME/.config/chatgpt-context-mcp/env.

Create the fallback 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"

Do not commit token files or real bearer tokens.

Codex Config Example

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

Claude Code Config Example

{
  "mcpServers": {
    "chatgpt_context": {
      "command": "<repo-path>/scripts/start-mcp.sh",
      "args": [],
      "env": {
        "CHATGPT_CODEX_MCP_ENV_FILE": "$HOME/.config/chatgpt-context-mcp/env"
      }
    }
  }
}