Metadata-Version: 2.4
Name: node804-claude-code-mcp
Version: 1.0.0
Summary: MCP server for reading Claude Code session history from the local filesystem
Project-URL: Homepage, https://github.com/Node804/node804-claude-code-mcp
Project-URL: Repository, https://github.com/Node804/node804-claude-code-mcp
Project-URL: Issues, https://github.com/Node804/node804-claude-code-mcp/issues
Author-email: Michael Pope <me@michaelpope.cv>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,claude-code,knowledge-management,mcp,model-context-protocol,pkm,session-history
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: mcp[cli]>=1.3.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# node804-claude-code-mcp

[![PyPI version](https://img.shields.io/pypi/v/node804-claude-code-mcp)](https://pypi.org/project/node804-claude-code-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/node804-claude-code-mcp)](https://pypi.org/project/node804-claude-code-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/Node804/node804-claude-code-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Node804/node804-claude-code-mcp/actions/workflows/ci.yml)

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.

---

## Installation

```bash
pip install node804-claude-code-mcp
```

Or install from source:

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

```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`:

```json
{
  "mcpServers": {
    "claude-code-logs": {
      "command": "python",
      "args": ["-m", "node804_claude_code_mcp.server"]
    }
  }
}
```

---

## Environment variables

| Variable     | Default      | Description                                |
|-------------|-------------|--------------------------------------------|
| `CLAUDE_DIR` | `~/.claude` | 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                         |
|---------------|--------|---------|-------------------------------------|
| `project_slug` | string | —       | Filter to one project (optional)    |
| `limit`        | 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                            |
|-------------------|---------|---------|----------------------------------------|
| `session_id`      | string  | —       | Session UUID                           |
| `project_slug`    | string  | —       | Project the session belongs to         |
| `include_thinking` | bool   | false   | Include assistant thinking blocks      |

---

### `get_claude_session_stats`
Token usage, timing, and message counts for a session.

| Argument       | Type   | Description        |
|---------------|--------|--------------------|
| `session_id`  | string | Session UUID       |
| `project_slug`| 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                          |
|---------------|--------|---------|--------------------------------------|
| `query`       | string | —       | Text to search for                   |
| `project_slug`| string | —       | Limit to one project (optional)      |
| `limit`       | 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](LICENSE).
