Skip to main content
Glama
Node804

node804-claude-code-mcp

by Node804

node804-claude-code-mcp

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.


Related MCP server: Claude Code History MCP Server

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.

Available Tools

6 tools
get_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.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYes
project_slugYes
include_thinkingNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden and effectively discloses that the tool returns a transcript with ordered messages and timestamps, excludes internal thinking blocks by default, and that these can be included via the include_thinking parameter. No destructive behavior is implied, and no contradictions exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with a clear opening sentence stating the purpose, followed by a brief summary of return content, and an organized list of parameters. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description adequately covers expected return content (messages, timestamps, tool names) and optional thinking. It lacks mention of error handling or edge cases, but overall provides sufficient context for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Since the input schema has 0% description coverage, the description fully compensates by explaining that session_id is a UUID from list_claude_sessions, project_slug identifies the project, and include_thinking controls inclusion of thinking blocks, with default false. Each parameter's meaning and source are clarified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the full conversation transcript from a Claude Code session, specifying it returns user and assistant messages with timestamps and tool call names, distinguishing it from sibling tools like get_claude_session_stats which provides statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool does and returns, but does not explicitly state when to use this tool versus alternatives like search_claude_sessions or list_claude_sessions. No exclusions or context for when not to use are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_idYes
project_slugYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description partially discloses behavior by listing return fields (token totals, duration, etc.) and required inputs. It does not mention error conditions, side effects, or performance implications, but provides a reasonable baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: three sentences plus a compact bullet list. The purpose is front-loaded in the first sentence, and every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema (not shown), the description adequately covers key return aspects (tokens, timing, models, directory). It lacks mention of error handling or validation, but is functionally complete for a stats tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It briefly explains 'session_id: The session UUID' and 'project_slug: The project the session belongs to', adding meaningful context beyond the schema titles.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to get token usage, timing, and message counts for a Claude Code session. It specifies the resource (session) and differentiates from sibling tools like get_claude_session (likely retrieves session details) and list_claude_sessions (lists all sessions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage via required parameters but does not explicitly state when to use this tool versus alternatives like get_claude_session or search_claude_sessions. No guidance on when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the data source (`~/.claude/projects/` or `CLAUDE_DIR`) and the sorting order. With no annotations, it carries full burden for transparency. Missing details on error handling (e.g., missing directory) and permissions, but adequate for a simple read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences covering purpose, source, and output details with no fluff. Perfectly concise and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with an output schema, the description is complete: it specifies the operation, data source, and return fields with sorting. No major gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the description adds value by explaining the data source and return fields, providing context beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists Claude Code projects, with specifics on what is returned (slug, session count, last activity timestamp) and sorting order. However, it does not explicitly differentiate from sibling tools like list_claude_sessions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., list_claude_sessions). The description implies it is a read operation but lacks explicit context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
project_slugNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It explains the behavior of the two parameters (filtering by project, limiting results) but does not disclose other behavioral traits such as read-only nature, sorting order, pagination details beyond limit, or any side effects. The description is adequate but lacks broader context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, clear, and uses a structured bullet format for arguments. No unnecessary words, and the key information is front-loaded. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with 2 optional parameters and an output schema, the description covers the essential parameter behavior and filtering logic. However, it could mention that the result is a list of sessions (though output schema likely handles that) and any default ordering. Overall, it is mostly complete given the tool's simplicity and available schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully explains both parameters: project_slug (use from list_claude_projects, leave empty for all) and limit (max number, default 20). It adds critical meaning that the schema alone does not provide, making parameter usage clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List Claude Code sessions' with optional filtering by project. It distinguishes itself from sibling tools like get_claude_session (single session) and search_claude_sessions (search) by being a general listing tool. The purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how to use the project_slug parameter (from list_claude_projects) and when to leave it empty, but does not explicitly state when to use this tool over siblings like search_claude_sessions or get_claude_session. Usage context is implied but not compared with alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryYes
project_slugNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions case-insensitive full-text search and returned fields (snippets, IDs, timestamps) but omits details on performance, rate limits, result ordering, or pagination behavior. The read-only nature is implied but not explicitly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by concise behavioral details and an Args block. It avoids fluff, though the Args section could be integrated more seamlessly. Overall efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 params, one required), the description covers purpose, match behavior, and all parameters. An output schema exists, so detailed return value documentation is not needed. No annotations exist, but the description is sufficient for a safe search operation. Missing: no mention of error cases or result ordering.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description must compensate. It adds meaningful context for all three parameters: query is 'Text to search for', project_slug limits to a project (empty for all), and limit sets max hits (default 20). This goes beyond the schema's raw structure, though the query parameter could include case-insensitivity detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches for text across Claude Code session messages, specifying case-insensitive full-text search over user and assistant messages, and returning snippets with context, session IDs, and timestamps. This distinguishes it from sibling tools like get_claude_session (retrieve single session) and list_claude_sessions (list sessions).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when searching session text but does not explicitly state when to use this tool versus alternatives like get_claude_session for retrieving a specific session or list_claude_sessions for listing. No exclusions or prerequisites are mentioned, leaving the agent to infer usage context from sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

server_statusA

Show the current server configuration.

Returns the version, the resolved Claude Code data directory, and the number of projects found.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description implies read-only operation but doesn't explicitly state side effects or safety. Adequate for a simple info tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with main purpose, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists; description summarizes key return fields. Complete for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters; description adds no param info but baseline for 0 parameters is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it shows server configuration and lists specific returned fields (version, directory, projects count). Distinct from sibling tools that deal with sessions/projects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use, but context from siblings implies it's for general server info. Adequate but could be more explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A4.1/5.0
Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

6 tools is well-scoped for a Claude Code session server. It covers listing, searching, retrieving details, and stats without being bloated or insufficient.

Completeness4/5

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

ActivityStale
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Node804/node804-claude-code-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server