gpt-history-mcp

English | 日本語

An MCP server (stdio) that lets your AI assistant search and read your ChatGPT conversations.

No data export and no scraping: it reads the conversation catalog that the ChatGPT desktop app already syncs to disk, and fetches message bodies from ChatGPT on demand.

You:    Find the chat where I discussed our ICP with ChatGPT and summarize it.
Claude: → search_chatgpt_messages("ICP") → get_chatgpt_chat("6aa…") → summary

Features

• Title search, offline: queries the local catalog kept by the ChatGPT desktop app

• Full-text search: searches message bodies through ChatGPT's own search, with snippets

• Read a conversation: returns the visible branch as a clean user / assistant transcript

• Read-only by design: only GET requests. The local database is opened read-only. Tokens never appear in logs or output.

Related MCP server: chatgpt-conversations-mcp

Requirements

• macOS with the ChatGPT desktop app (the version with Codex built in), signed in and synced

• ~/.codex/auth.json holding a ChatGPT login. Run codex login and sign in with your ChatGPT account to create it.

• Bun 1.4 or later. The server must run on Bun: other HTTP clients are blocked by Cloudflare.

Installation

Quick start with npx

No clone needed. npx fetches the package from npm and runs it with Bun, so bun must be on your PATH:

claude mcp add --scope user gpt-history-mcp -- npx -y gpt-history-mcp

For other clients, use "command": "npx" and "args": ["-y", "gpt-history-mcp"] in the examples below.

From a clone

git clone https://github.com/YunosukeYoshino/gpt-history-mcp.git
cd gpt-history-mcp
bun install

Then register the server with your MCP client. In the examples below, replace /path/to/gpt-history-mcp with the absolute path of your clone. GUI apps may not inherit your shell's PATH, so use the absolute path of bun there (find it with which bun, e.g. /usr/local/bin/bun).

Claude Code

claude mcp add --scope user gpt-history-mcp -- bun /path/to/gpt-history-mcp/src/index.ts

To share it with a single project instead, put this .mcp.json at that project's root:

{
  "mcpServers": {
    "gpt-history-mcp": {
      "command": "bun",
      "args": ["/path/to/gpt-history-mcp/src/index.ts"]
    }
  }
}

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json, then restart the app:

{
  "mcpServers": {
    "gpt-history-mcp": {
      "command": "/usr/local/bin/bun",
      "args": ["/path/to/gpt-history-mcp/src/index.ts"]
    }
  }
}

Codex (CLI and ChatGPT desktop)

Add this to ~/.codex/config.toml:

[mcp_servers.gpt-history-mcp]
command = "/usr/local/bin/bun"
args = ["/path/to/gpt-history-mcp/src/index.ts"]

Cursor

Use the same mcpServers JSON as Claude Desktop, in ~/.cursor/mcp.json (or .cursor/mcp.json for a single project).

Verify

Call search_chatgpt_chats with an empty query from your client. It should list your recent chats. To test the server on its own, use the MCP Inspector:

bunx @modelcontextprotocol/inspector bun /path/to/gpt-history-mcp/src/index.ts

Tools

• search_chatgpt_chats matches titles only. All space-separated words must match. An empty query lists the most recent chats.

• search_chatgpt_messages also searches message bodies. Use it when the title is not enough.

• get_chatgpt_chat returns only the branch currently shown in ChatGPT. System messages, tool messages and hidden messages are dropped.

How it works

~/.codex/sqlite/codex-dev.db          ~/.codex/auth.json
  local_thread_catalog                  tokens.access_token
  (source_kind = 'chatgpt')                   │
        │                                     ▼
  search_chatgpt_chats           chatgpt.com/backend-api  (Bun fetch)
                                   ├─ conversations/search → search_chatgpt_messages
                                   └─ conversation/{id}    → get_chatgpt_chat

• The ChatGPT desktop app writes to the catalog database while it runs, so gpt-history-mcp opens it read-only.

• Codex refreshes the token in auth.json, so gpt-history-mcp re-reads the file on every request.

Configuration

Troubleshooting

Development

bun test            # unit tests. They never touch the real API or your credentials.
bunx tsc --noEmit   # type check
bun start           # start the stdio server (usually launched by an MCP client)

src/
├── index.ts      MCP server and tool registration
├── catalog.ts    catalog search (bun:sqlite, read-only)
├── chatgpt.ts    auth loading, GET-only backend-api client, response normalization
├── linearize.ts  conversation tree → ordered messages
├── paths.ts      CODEX_HOME resolution
└── time.ts       Unix seconds → ISO 8601
test/             bun test (fixtures, fake fetch, temp files)

Contributor and agent guidelines are in AGENTS.md.

License

MIT