# 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](assets/real-run.png)

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`](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

```bash
git clone https://github.com/dambinhtu-nhuy/claude-code-session-mcp
cd claude-code-session-mcp
npm install
npm test
```

### Claude Code

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

Or drop this in `.mcp.json` at the root of a project:

```json
{
  "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`](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:

```bash
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.