Content
# 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
