node804-claude-code-mcp

MCP server for reading Claude Code session history from the local filesystem. Exposes project and session data to any MCP-compatible client — Claude Cowork, Claude Chat, scheduled agents, or your own tooling.

Reads directly from ~/.claude/projects/ — no external dependencies, no network calls, no API keys.

Why this exists

Claude Code stores every session as a local JSONL file containing the full conversation: user messages, assistant responses, tool calls, token counts, and timing. That history is rich and detailed, but it's locked inside the CLI with no way to query it from other tools.

This server opens it up.

Use cases

Personal Knowledge Management and daily logging Claude Code sessions are a detailed record of decisions made, problems solved, and code written. This server lets a Cowork or Chat session pull that raw material into a daily note, work log, or PKM entry automatically — capturing not just what changed but the reasoning behind it, without any manual copy-paste.

Cross-session continuity Starting a new Claude Code session on a project that was last touched weeks ago means re-explaining context from scratch. With this server, a fresh session can search prior conversations for relevant background — design decisions, dead ends already explored, environment quirks — before writing a single line of code.

Standup and progress reporting search_claude_sessions and get_claude_session_stats give enough signal to reconstruct what was worked on across a day or week. A scheduled agent can draft standup notes or weekly summaries without you keeping a separate activity log.

Token and time auditing get_claude_session_stats returns per-session input/output token counts, cache hit rates, and duration. Useful for understanding which projects are consuming the most AI time, or for back-of-envelope cost tracking across a team.

Recovering decisions and rationale The assistant messages in a session contain reasoning that never makes it into git history or documentation. When a colleague asks "why did we pick X over Y?", a search across sessions is often faster than reading commits — and captures the full deliberation, not just the outcome.

Handoff and onboarding A new team member or a handoff to another AI session can be primed with the actual conversation history from a project rather than a manually written summary that may already be stale.

Research and spike synthesis Exploratory sessions — spiking on a library, investigating an incident, prototyping an approach — produce valuable findings that are easy to lose. Searching across those sessions lets later work build on earlier exploration rather than repeat it.

Installation

pip install node804-claude-code-mcp

Or install from source:

git clone https://github.com/Node804/node804-claude-code-mcp
cd node804-claude-code-mcp
pip install -e .

Setup

Claude Desktop / Claude Chat

Add to claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "claude-code-logs": {
      "command": "python",
      "args": ["-m", "node804_claude_code_mcp.server"]
    }
  }
}

Restart Claude Desktop after saving.

Claude Code (settings.json)

Add to .claude/settings.json in your project, or to the global ~/.claude/settings.json:

{
  "mcpServers": {
    "claude-code-logs": {
      "command": "python",
      "args": ["-m", "node804_claude_code_mcp.server"]
    }
  }
}

Environment variables

Tools

server_status

Show the current server version and resolved data directory.

list_claude_projects

List all Claude Code projects in the local session store, sorted by most recent activity.

Returns: project slug, session count, last activity timestamp.

list_claude_sessions

List sessions for a specific project or all projects.

get_claude_session

Get the full conversation transcript from a session. Returns user and assistant messages in order, with timestamps and tool call names.

get_claude_session_stats

Token usage, timing, and message counts for a session.

Returns: input/output tokens, cache read tokens, duration in minutes, models used, working directory.

search_claude_sessions

Case-insensitive full-text search across all session messages. Returns matching snippets with surrounding context.

Known limitations

Session files are read linearly from top to bottom. Claude Code's JSONL format is actually a tree — every record links to its parent via parentUuid, which means a session can contain forks (abandoned tool call branches, retries, compaction summaries). Linear reading is correct for the vast majority of normal interactive sessions, but a forked session could include abandoned branches in the output. Fork-aware traversal that follows the primary thread and discards dead branches is a potential future improvement.

Data locations

Claude Code stores session data at:

• Windows: %USERPROFILE%\.claude\projects\
• macOS / Linux: ~/.claude/projects/

Each project directory contains one .jsonl file per session. Records include user messages, assistant messages (with tool calls and token usage), and internal control messages.

License

MIT — see LICENSE.