node804-claude-code-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@node804-claude-code-mcp list my claude code projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Claude Code History MCP Server
Installation
pip install node804-claude-code-mcpOr 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 |
|
| 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 |
| string | — | Filter to one project (optional) |
| 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 |
| string | — | Session UUID |
| string | — | Project the session belongs to |
| bool | false | Include assistant thinking blocks |
get_claude_session_stats
Token usage, timing, and message counts for a session.
Argument | Type | Description |
| string | Session UUID |
| 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 |
| string | — | Text to search for |
| string | — | Limit to one project (optional) |
| 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.
Available Tools
6 toolsget_claude_sessionA
Get the full conversation transcript from a Claude Code session.
Returns user and assistant messages in order, with timestamps and tool call names. Internal thinking blocks are excluded unless include_thinking is set.
Args: session_id: The session UUID (as returned by list_claude_sessions). project_slug: The project the session belongs to. include_thinking: Include assistant thinking blocks. Defaults to False.
Inputs: session_id (required), project_slug (required), include_thinking. Returns: object
get_claude_session_statsA
Get token usage, timing, and message counts for a Claude Code session.
Returns input/output token totals, cache read tokens, duration in minutes, models used, and the working directory the session was run from.
Args: session_id: The session UUID. project_slug: The project the session belongs to.
Inputs: session_id (required), project_slug (required). Returns: object
list_claude_projectsA
List all Claude Code projects in the local session store.
Reads from ~/.claude/projects/ (or CLAUDE_DIR if set).
Returns each project's slug, session count, and last activity timestamp,
sorted most-recent first.
Inputs: no named parameters. Returns: object
list_claude_sessionsA
List Claude Code sessions, optionally filtered to a single project.
Args: project_slug: The project slug (as returned by list_claude_projects). Leave empty to list sessions across all projects. limit: Maximum number of sessions to return. Defaults to 20.
Inputs: limit, project_slug. Returns: object
search_claude_sessionsA
Search for text across Claude Code session messages.
Case-insensitive full-text search over all user and assistant messages. Returns matching snippets with surrounding context, session IDs, and timestamps.
Args: query: Text to search for. project_slug: Limit search to a single project. Leave empty to search all projects. limit: Maximum number of hits to return. Defaults to 20.
Inputs: query (required), limit, project_slug. Returns: object
server_statusA
Show the current server configuration.
Returns the version, the resolved Claude Code data directory, and the number of projects found.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a unique aspect: server_status for config, list_claude_projects for projects, list_claude_sessions for sessions, search_claude_sessions for full-text search, get_claude_session for transcripts, and get_claude_session_stats for metrics. There is no functional overlap.
Most tools follow a verb_noun pattern (list_claude_projects, list_claude_sessions, search_claude_sessions, get_claude_session, get_claude_session_stats). server_status is a slight deviation (noun_noun) but still clear and readable.
6 tools is well-scoped for a Claude Code session server. It covers listing, searching, retrieving details, and stats without being bloated or insufficient.
The tool surface covers core read operations for projects and sessions, including search and statistics. No obvious missing functionality for inspection, though write/delete operations are absent by design (sessions are managed externally).
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Read-only MCP server exposing a user ORANO library to their own AI agent.
An MCP server for search and retrieval over a local LanceDB database
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server for managing Claude Code conversation sessions12MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables users to retrieve, filter, and search through Claude Code conversation history stored in local projects. It provides tools for listing projects and sessions, paginating through message history, and searching across conversations with keyword filtering.421 npm11MIT
- AlicenseBqualityDmaintenanceMCP server for accessing Claude Code plugins. Enables retrieving plugin lists and detailed information via MCP clients like Claude Desktop, Cursor.2MIT
- FlicenseAqualityDmaintenanceFork-aware MCP server for searching and navigating Claude Code session history.6-