# ChatGPT Conversations MCP

I built this because I wanted my AI to be able to see my other ChatGPT conversations and actually talk to them.

ChatGPT Desktop already has some of the plumbing for this internally. This MCP uses that native path instead of scraping cookies, driving the UI with screenshots, or asking you for an OpenAI API key.

Right now it can:

- list your normal ChatGPT conversations;
- read one without opening it in the UI;
- send a message into an existing conversation;
- wait for that same turn's assistant reply and bring it back through MCP.

That means one AI session can do something as simple as:

```text
find the conversation about X
read it
ask that conversation Y
bring the answer back here
```

It's early. The core works, the safety rules are deliberate, and there are still Desktop-version rough edges I want to harden. That's why this is a preview rather than me pretending it's a finished 1.0.

![How the bridge works](assets/architecture.png)

## What makes this different

There are already projects that automate the ChatGPT window. That's not what this is doing.

The bridge talks to the native tool host exposed by the Windows ChatGPT Desktop app through a local named pipe. The destination conversation stays separate from the private carrier thread used to make that native call.

So the useful bit is not "AI clicks ChatGPT for you". It's closer to:

```text
MCP client
    ↓ stdio
chatgpt-conversations-mcp
    ↓ framed JSON-RPC
ChatGPT Desktop native tool pipe
    ↓
your existing ChatGPT conversations
```

No browser screenshots are needed for conversation operations. No ChatGPT cookies are copied. No OpenAI API key is required by this MCP.

The project is unofficial and is not affiliated with or endorsed by OpenAI.

## The three tools

| Tool | Type | What it does |
| --- | --- | --- |
| `chatgpt_conversations` | READ | Lists normal ChatGPT conversations. |
| `chatgpt_conversation` | READ | Reads turns from one normal ChatGPT conversation. |
| `chatgpt_message` | WRITE | Sends one message to an existing conversation and observes that turn for the reply. |

![Public MCP action classification](assets/mcp-actions.png)

The write tool is deliberately advertised as:

- not read-only;
- not destructive;
- not idempotent;
- closed-domain (`openWorldHint: false`).

That last bit matters. The tool can only continue an existing conversation in the connected ChatGPT account. It is not a general "go do stuff on the internet" action.

More detail, including the exact JSON Schemas, is in [`docs/mcp-tools.md`](docs/mcp-tools.md).

## Write safety

I don't silently retry messages.

If the native send throws after the request may already have reached ChatGPT, the result is treated as uncertain. The MCP then reads the target conversation and looks for the exact new user turn. If it can't prove what happened before the deadline, it returns `delivery_uncertain`.

If you see that status, **don't just send the same message again**. Read the conversation first and check whether it landed.

This is boring on purpose. Duplicate AI messages are worse than admitting the transport got weird.

## Quick start

You need:

- Windows;
- Node.js 22 or newer;
- the current ChatGPT Desktop app installed and signed in;
- Codex available from that local ChatGPT/OpenAI install.

Clone the repo, then:

```powershell
npm ci
npm run create:carrier
```

The carrier helper starts a harmless local Codex thread and reads only the explicit `thread.started` ID from Codex JSON output. Keep that ID private.

Set it for your current shell:

```powershell
$env:CHATGPT_CONVERSATIONS_CARRIER_THREAD_ID = '<YOUR_PRIVATE_CARRIER_THREAD_ID>'
```

Then run the read-only setup check:

```powershell
npm run verify:setup
```

If that works, point your MCP host at `src/server.mjs`. A generic stdio example is in [`examples/mcp-config.example.json`](examples/mcp-config.example.json).

Full Windows setup is in [`docs/windows-setup.md`](docs/windows-setup.md).

## Proof, not vibes

Before I call a build release-ready I want this path to work from a clean clone:

```text
install → create carrier → verify → list → read → send once → receive reply
```

And I want it three clean times, from three clean clones, without hidden local setup doing the work.

![Real cross-chat proof](assets/cross-chat-demo.png)

![Test suite proof](assets/tests.png)

The automated suite also checks the stuff I don't want to learn the hard way later:

- carrier and destination stay separate;
- Codex threads don't leak through the public conversation tools;
- reads can recover from a stale Desktop pipe;
- an uncertain write is never auto-retried;
- the public tree is scanned for private paths, secret-shaped values, real `.env` files and private infrastructure names.

## Known rough edges

This depends on native behavior in ChatGPT Desktop that OpenAI can change. A Desktop update can break pipe discovery or change an internal response shape before this repo has caught up.

The current preview is Windows-first. It is not a hosted service and it does not include somebody else's gateway or tunnel setup.

`chatgpt_message` waits for the matching assistant reply, but a slow or interrupted turn can end as `sent_reply_pending` or `delivery_uncertain`. Those states are part of the contract, not hidden errors.

## If you're pointing an AI at this repo

Good. Start with [`FOR_AI.md`](FOR_AI.md).

The short version is: don't judge this from the README alone. Read the tool schemas, `src/native-call.mjs`, `src/refreshing-bridge.mjs`, and `src/message-service.mjs`. That's where the important decisions are.

If you want to rebuild the same idea in another language, crack on. [`docs/reimplementation.md`](docs/reimplementation.md) is there specifically for that.

## Where this can go

The first preview is intentionally just conversations. I don't want to turn one working primitive into twelve half-built features.

Stuff I want to explore next:

- conversations inside ChatGPT Projects;
- opening or focusing a conversation;
- project-aware discovery;
- richer cross-conversation orchestration;
- loading agent definitions from a local agent directory;
- assigning specialised agents to conversations;
- multi-conversation workflows.

Those are directions, not shipped features.

## Docs

- [`docs/architecture.md`](docs/architecture.md) — the moving parts and data flow.
- [`docs/mcp-tools.md`](docs/mcp-tools.md) — exact public tool contracts.
- [`docs/native-desktop-bridge.md`](docs/native-desktop-bridge.md) — what the Desktop bridge is doing.
- [`docs/windows-setup.md`](docs/windows-setup.md) — clean setup from clone to MCP.
- [`docs/security.md`](docs/security.md) — trust boundary and write safety.
- [`docs/reimplementation.md`](docs/reimplementation.md) — enough detail to build your own version.
- [`docs/troubleshooting.md`](docs/troubleshooting.md) — when Desktop decides to be Desktop.

## Licence

Apache-2.0. Use it, fork it, learn from it, rebuild it. See [`LICENSE`](LICENSE).

If you find a security issue, read [`SECURITY.md`](SECURITY.md) before posting details publicly.