# claude-web-history-mcp

I have ideas on my phone. I write code in VS Code. Those two things don't talk
to each other, so every time I sat down to actually build something, the
conversation where I worked it out was stuck on the other side of a wall.

This is an MCP server that tears down that wall — it lets **Claude Code** browse
and pull in conversations from your **claude.ai** account, so a chat you had on
your phone this morning is available in your editor this afternoon.

You choose which conversation to import. Nothing syncs automatically, nothing is
written back to claude.ai, and no credential ever lands in a config file.

## Before you use this: terms of service

**Anthropic's Consumer Terms of Service prohibit what this tool does.** Section 3
prohibits accessing the service "through automated or non-human means, whether
through a bot, script, or otherwise," with the only carve-out being an official
API key or Anthropic's explicit permission. That clause has been in place since
February 2024 and has been enforced — in early 2026, accounts using third-party
harnesses were terminated under it.

I'm not going to tell you this is fine. Read the terms yourself:
<https://www.anthropic.com/legal/consumer-terms>. Decide for yourself.

What I can offer is the distinction I found relevant when deciding to use it
myself. The enforcement action in 2026 targeted tools that routed *inference
traffic* through consumer subscriptions — using a flat-rate plan to avoid API
costs. This tool consumes no inference quota. It makes a few read-only requests
for conversations you already created, data Anthropic also hands you via the
official export feature under Settings.

That is a difference in kind, not a legal exemption. The clause doesn't have a
"but it's read-only" exception. I judge the practical risk to be low. **That is a
judgment, not a promise, and I have no standing to make promises about how
Anthropic enforces its terms.** If you get your account suspended, that's your
account, not mine.

If any of that gives you pause, stop here. The official export under Settings
gets you the same data, slower and manually, with zero risk. It's a real option
and for many people it's the right one.

## Other things you should know

- **Your session key is equivalent to your claude.ai login.** Anyone who obtains
  it can act as you. This code stores it in your OS keychain and only ever sends
  it to `claude.ai` — but you should verify that claim rather than take my word
  for it.
- **Don't paste your session key into any tool you haven't read the source of.**
  Including this one. It's ~850 lines across four files, deliberately, so that
  reading it is realistic. Please do. Start with `claude-web.js`.
- **Be careful with forks.** This code is short and simple enough that adding
  three lines to exfiltrate your key would be easy and easy to miss. Read the
  diff of whatever you actually run.
- **This uses undocumented endpoints and will break** when Anthropic changes the
  web app. Treat it as disposable.
- **Anthropic has an open feature request for an official version**
  (`anthropics/claude-code` #15542). That's the real fix. If it ships,
  delete this. Adding your use case to that thread is more useful than starring
  this repo.

## Requirements

- Node.js 18+
- Claude Code (CLI, VS Code, JetBrains, or desktop — they share one config)
- Works on macOS, Windows, and Linux

## Install

Read the source first. Seriously — see the section above.

```bash
git clone https://github.com/DestinyJazz/claude-web-history-mcp.git
cd claude-web-history-mcp
npm install
npm run auth
```

`npm run auth` walks you through finding your session key, stores it in your
**OS keychain** (macOS Keychain / Windows Credential Manager / Linux Secret
Service), verifies it against claude.ai, and prints the exact command to
register the server. Input is hidden while you type.

Then run the command it gives you — roughly:

```bash
claude mcp add claude-web-history --transport stdio -s user -- node /abs/path/to/index.js
```

There's deliberately **no `--env` flag**: the key lives in the keychain, not in
`~/.claude.json`.

Open the Claude Code panel, type `/mcp`, confirm it connected. Done.

### You don't need to keep anything running

This is a stdio server. Claude Code spawns it on demand and it exits when the
call finishes. Nothing to start, nothing to leave open, survives reboots.

## Using it

Just talk to Claude Code:

> List my recent claude.ai conversations about the auth redesign

> Read conversation `abc-123` and use it as context for what we're building here

> Save conversation `abc-123` to `docs/context/auth-design.md`

That last one is worth a habit: parking an important conversation as a file in
the repo means it survives even if this server stops working.

## Tools

| Tool | What it does |
|---|---|
| `list_web_conversations` | Lists your claude.ai chats. Supports `limit`, `offset`, and a `contains` title filter. |
| `read_web_conversation` | Pulls one conversation into the session as markdown. Truncates at `max_chars` (default 60k). |
| `save_web_conversation` | Writes a conversation to a file in your repo. |
| `debug_connection` | Verifies the session and shows the resolved org id. Pass `raw_path` to inspect a raw endpoint when something breaks. |

## Credentials

| Command | Effect |
|---|---|
| `npm run auth` | Store or replace the session key. |
| `npm run check` | Verify the stored key still works. |
| `npm run auth -- --remove` | Delete the key from the keychain. |

**Resolution order:** `CLAUDE_SESSION_KEY` env var (escape hatch, CI, headless
Linux) → OS keychain (the default).

Session keys expire every few weeks, or immediately if you log out in the
browser. When they do, tools return a message telling you to run `npm run auth`.

**Safeguards in the code, so you can verify them:**

- The key is stored via `@napi-rs/keyring` — never written to a config file.
- A hardcoded host allowlist means the server refuses to send the cookie
  anywhere but `claude.ai`. See `ALLOWED_HOSTS` in `claude-web.js`.
- All output and error text passes through `redact()` before leaving the server,
  so a key can't leak into the model's context or a transcript.
- Setup input is read with terminal echo off.
- No logging to disk. Ever.

### Other env vars

| Var | Purpose |
|---|---|
| `CLAUDE_ORG_ID` | Skip org lookup by pinning your org uuid. |
| `CLAUDE_WEB_BASE` | Override the base URL. Must still resolve to claude.ai. |
| `CLAUDE_WEB_UA` | Override the User-Agent string. |

## When it breaks

Run `debug_connection`, or `npm run check` from a terminal.

- **"Session expired or missing"** → run `npm run auth` with a fresh key.
- **HTTP 404** → the endpoint moved. Open claude.ai with DevTools → Network,
  click through your chat list, and compare against the `EP` block at the top of
  `claude-web.js`. That's the only place paths are defined — one edit fixes it.
- **List works but message text is empty** → the message payload shape changed.
  See the `content[]` handling in `getConversation()`.
- **Keychain unavailable** (headless Linux, no Secret Service) → set
  `CLAUDE_SESSION_KEY` as an env var instead.

## Layout

```
index.js        MCP server — tool definitions
claude-web.js   claude.ai client — all endpoints live at the top
credentials.js  keychain storage, key normalization, redaction
setup.js        interactive `npm run auth`
```

Dependency direction is one-way: `index.js` and `setup.js` both depend on
`claude-web.js`, which depends only on `credentials.js`. Reading those last two
is enough to confirm where the key can and can't go.

## License

MIT. Not affiliated with, endorsed by, or supported by Anthropic.