# local-claude-chat-history-mcp

An MCP server that searches your **local** Claude conversation history — the sessions Claude stores as files on your own machine.

| Source | Location | What it is |
|--------|----------|------------|
| `code` | `~/.claude/projects/**/*.jsonl` | Claude Code CLI/desktop sessions |
| `cowork` | `~/Library/Application Support/Claude/local-agent-mode-sessions` (macOS) | Claude Cowork (local agent mode) sessions |

Everything runs locally over stdio — it only reads files already on disk, and nothing is uploaded anywhere.

Handy for questions like:

- *"What did I work on today / this week?"*
- *"Which session was it where I set up the ADX proxy?"*
- *"When did I last touch the leaderboard caching code?"*

> **Scope — local only.** This searches the transcripts Claude writes to disk (Claude Code and Claude Cowork). Your regular **claude.ai / Claude Desktop chats are stored in Anthropic's cloud, not locally**, so there is no local file for this tool to read and they are intentionally out of scope.

## Usage

### Claude Code plugin (recommended)

This repo is a Claude Code plugin and its own marketplace. Install it with:

```bash
# From GitHub
claude plugin marketplace add daniellmorris/local-claude-chat-history-mcp
claude plugin install local-claude-chat-history@local-claude-chat-history

# Or from a local checkout
claude plugin marketplace add /path/to/local-claude-chat-history-mcp
claude plugin install local-claude-chat-history@local-claude-chat-history
```

Or interactively inside Claude Code: `/plugin marketplace add …` then `/plugin install local-claude-chat-history`.

The plugin runs the bundled server at `dist/server.mjs` — no `npm install` needed on the machine that installs it.

For quick testing without installing:

```bash
claude --plugin-dir /path/to/local-claude-chat-history-mcp
```

### Claude Code (plain MCP server)

```bash
claude mcp add claude-history -- npx -y github:daniellmorris/local-claude-chat-history-mcp
```

### Claude Desktop / other MCP clients

```json
{
  "mcpServers": {
    "claude-history": {
      "command": "npx",
      "args": ["-y", "github:daniellmorris/local-claude-chat-history-mcp"]
    }
  }
}
```

## Tools

### `search_history`

Full-text search across both sources, newest sessions first.

| Param | Default | Description |
|-------|---------|-------------|
| `query` | — | Case-insensitive substring (or regex with `regex: true`) |
| `source` | `all` | `all` \| `code` \| `cowork` |
| `project` | — | Substring filter on project path or session title |
| `role` | `any` | `user` \| `assistant` |
| `after` / `before` | — | ISO date bounds (e.g. `2026-07-09`) |
| `limit` / `maxPerSession` | 20 / 3 | Result caps |

Returns matching snippets with `sessionId`s.

### `list_sessions`

Browse recent sessions (id, title, project, timestamps) with the same `source`/`project` filters. Great for "what did I do today".

### `get_session`

Read a full conversation by `sessionId`, paginated with `offset`/`limit`, each message truncated to `maxChars`.

## Configuration

All optional, via environment variables:

| Variable | Purpose |
|----------|---------|
| `CLAUDE_CODE_HISTORY_DIR` | Override `~/.claude/projects` |
| `CLAUDE_COWORK_SESSIONS_DIR` | Override the Cowork sessions directory |

## Development

```bash
npm install
npx @modelcontextprotocol/inspector node index.js
```

The plugin ships a dependency-free bundle at `dist/server.mjs` (committed to the repo). After changing `index.js` or `lib/`, rebuild it:

```bash
npm run build
```

## License

MIT