node804-claude-code-mcp
Click on "Install 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-mcplist 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.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | ||
| project_slug | Yes | ||
| include_thinking | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | ||
| project_slug | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| project_slug | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| project_slug | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
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.
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.
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.
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.
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.
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
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
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
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
OAuth-protected, read-only-by-default MCP server for provenance-labeled QuillCaddie project memory.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server for managing Claude Code conversation sessions1278MIT
- 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.42811MIT
- AlicenseBqualityDmaintenanceMCP server for accessing Claude Code plugins. Enables retrieving plugin lists and detailed information via MCP clients like Claude Desktop, Cursor.2MIT
- FlicenseNot gradedqualityFmaintenanceAn MCP server for coordinating multiple Claude Code sessions across related projects.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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