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.

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.