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:

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

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

Claude Code (plain MCP server)

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

Claude Desktop / other MCP clients

{
  "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 sessionIds.

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

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:

npm run build

License

MIT