Skip to main content
Glama
claude-code-session-mcp

claude-code-session-mcp

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.

Claude Code calling tool_usage on this server and summarising the result

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

list_sessions

What happened, and when

project, since, until, limit

session_stats

Everything about one session

session_id

tool_usage

Which tools, how often

project, since, until

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 test

Claude Code

claude mcp add session-history -- node /absolute/path/to/server.mjs

Or 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.json

  • Windows %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.mjs

CLAUDE_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 logic

The 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.mjs

The 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\myapp becomes c--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 tools
list_sessionsList Claude Code sessionsA
Read-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 detailA
Read-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 sessionsA
Read-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

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      4
      21 npm
      11
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Exposes analytics from Claude Code transcripts as MCP tools, enabling cost, audit, safety, and efficiency queries through natural language.
      4
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables search, analytics, and visualization of Claude Code sessions with MCP tools for session management, recovery, and insights.
      10
      147 PyPI
      1
      MIT