Node804 Claude Code

PyPI version Python versions License: MIT CI

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

Variable	Default	Description
CLAUDE_DIR	~/.claude	Override the Claude Code data directory

---

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.

Argument	Type	Default	Description
project_slug	string	—	Filter to one project (optional)
limit	int	20	Max sessions to return

---

get_claude_session

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

Argument	Type	Default	Description
session_id	string	—	Session UUID
project_slug	string	—	Project the session belongs to
include_thinking	bool	false	Include assistant thinking blocks

---

get_claude_session_stats

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

Argument	Type	Description
session_id	string	Session UUID
project_slug	string	Project slug

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.

Argument	Type	Default	Description
query	string	—	Text to search for
project_slug	string	—	Limit to one project (optional)
limit	int	20	Max hits to return

---

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.