claude-code-session-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., "@claude-code-session-mcp What projects did I work on last week?"
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.
claude-code-session-mcp
An MCP server that lets Claude answer questions about your own Claude Code history, from the transcripts already sitting on your disk.
Three tools, all read-only. Ask "which projects did I work on last week", "what was the long session on Tuesday", "how much of this month was reading versus editing", and the model reaches for them on its own.

Nothing in that screenshot is staged. The question is one line of English, the
model picked tool_usage on its own and filled in project, since and until
from the wording, the JSON is exactly what the server returned, and the table is
the model's own summary of it. Two more runs, with the tool calls copied out of
the transcripts Claude Code wrote for them, are in
assets/real-run.md.
It counts, it does not read back
Claude Code transcripts contain everything you ever typed into it. A server that hands those back to a model is a liability, so this one is built the other way round: it reads the message text in order to count things, and returns only the counts. Prompts, replies and tool arguments never leave the process.
That is a claim worth testing rather than trusting. The fixtures carry a canary string in a prompt, in an assistant reply, and inside a tool argument, and two tests fail if it ever appears in an output: one on the reading layer, one on the far side of the protocol, checking the bytes that actually crossed the wire.
Related MCP server: cc-session-search
The three tools
Tool | Answers | Arguments |
| What happened, and when |
|
| Everything about one session |
|
| Which tools, how often |
|
Every session carries its project, time span, turn and prompt counts, subagent turns, per-model token usage split into input, output, cache read and cache write, a tally of tool calls by name, and a count of damaged lines.
Install
git clone https://github.com/dambinhtu-nhuy/claude-code-session-mcp
cd claude-code-session-mcp
npm install
npm testClaude Code
claude mcp add session-history -- node /absolute/path/to/server.mjsOr drop this in .mcp.json at the root of a project:
{
"mcpServers": {
"session-history": {
"command": "node",
"args": ["/absolute/path/to/server.mjs"]
}
}
}mcp-config.json in the repo root is that same block with a relative path, for
passing to claude --mcp-config while standing in this directory, which is how
the runs in assets/real-run.md were driven. Relative paths
only resolve from the repo root, so use the absolute form above for a real
install.
Claude Desktop
Same block, in claude_desktop_config.json:
macOS
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows
%APPDATA%\Claude\claude_desktop_config.json
Restart the app afterwards. Claude Desktop only reads the config at startup.
Trying it without exposing anything
Point the server at the fixtures instead of your real history:
CLAUDE_PROJECTS_DIR=./sample/projects node server.mjsCLAUDE_PROJECTS_DIR overrides the default of ~/.claude/projects. The test
suite uses it so no test ever touches a real session.
How it works
sessions.mjs reads the .jsonl transcripts, returns counts no MCP, no model
server.mjs declares three tools, speaks stdio no logicThe split is the point. All the counting lives in plain functions that take a string and return an object, which is why it can be tested against fixtures without a client, a network, or a model in the loop.
Two things are worth knowing if you are reading the code:
Cache tokens are reported two different ways depending on the client
version, either a flat cache_creation_input_tokens or a breakdown by TTL under
cache_creation. Reading only one of them silently undercounts.
A truncated last line is normal, because a live session is being appended to while you read it. Damaged lines are counted and reported rather than thrown, so one bad byte never hides a whole session, and the count tells you when a number is standing on incomplete data.
Tested
26 tests, 26 pass
test/sessions.test.mjs 19 the reading layer, against fixtures
test/protocol.test.mjs 7 a real MCP client, over stdio, spawning server.mjsThe protocol tests are the ones that matter for "does this work". They start
server.mjs as a child process, speak MCP to it, list the tools, call all
three, send a deliberately malformed argument, and confirm the server rejects it
by schema and is still answering afterwards.
Measured against a real transcript directory: 326 sessions, 27,392 assistant turns, 0 damaged lines, read in 1.9 seconds.
Limits worth stating
Read-only by design. There is no tool here that writes, moves or deletes anything.
Session content is not exposed and will not be added. If you want a model to read your old conversations back, this is the wrong tool.
Project names come from Claude Code, which derives them from the working directory with separators replaced by dashes, so
c:\dev\myappbecomesc--dev-myapp. There is no lookup back to the original path.Sessions are grouped by their start day. One that runs past midnight counts on the day it began.
License
MIT.
Available Tools
3 toolslist_sessionsList Claude Code sessionsARead-only
List past Claude Code sessions, newest first, with the project, time span, number of turns and prompts, per-model token usage and a tally of which tools were called. Use it to answer questions like which projects were worked on last week or which session was the long one. Returns counts only, never the text of any message.
Inputs: limit, since, until, project.
session_statsRead one session in detailARead-only
Full counts for a single session id: duration in seconds, turns, prompts, subagent turns, damaged lines, per-model token usage and the combined totals. Take the id from list_sessions. Returns counts only, never the text of any message.
Inputs: session_id (required).
tool_usageTally tool calls across sessionsARead-only
Count how often each Claude Code tool (Read, Edit, Bash, Grep and the rest) was called across the sessions matching the filters, most used first. Use it to answer questions about working habits, such as how much of a week was reading versus editing. Returns tool names and counts, never tool arguments.
Inputs: since, until, project.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinctly separate purpose: list_sessions provides an overview for browsing, session_stats drills into a single session's aggregate counts, and tool_usage analyzes tool call frequencies across sessions. There is no overlap or ambiguity in what each tool returns.
list_sessions follows a verb-noun pattern, while session_stats and tool_usage are noun-noun, but all use consistent snake_case and are immediately readable. The slight variation is predictable and does not cause confusion.
With only three tools, the server is tightly scoped to session statistics and aggregation. This count is well within the ideal 3-15 range, and each tool serves a necessary, non-redundant function for the stated purpose.
The tool set fully covers the intended workflow: listing sessions, viewing detailed stats for a specific session, and aggregating tool usage across sessions. The deliberate omission of message content is consistent with the server's focus on counts, leaving no obvious gaps.
Maintenance
Related MCP Connectors
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
An MCP server that provides congressional transcripts
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
MCP observability: analyse MCP server usage, investigate sessions, and instrument MCP servers.
Related MCP Servers
- 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
- FlicenseBqualityDmaintenanceAn MCP server that provides tools for searching and analyzing Claude Code conversation history.84-
- AlicenseAqualityCmaintenanceExposes analytics from Claude Code transcripts as MCP tools, enabling cost, audit, safety, and efficiency queries through natural language.4MIT
- AlicenseAqualityCmaintenanceEnables search, analytics, and visualization of Claude Code sessions with MCP tools for session management, recovery, and insights.10147 PyPI1MIT