What can you do with this server?

The Claude Historian server enables efficient search and analysis of Claude Code conversation history to find past solutions, track changes, and understand usage patterns. * **Search Conversations**: Find relevant conversations by query with optional project and timeframe filters * **Find File Context**: Retrieve conversations related to specific file paths * **Find Similar Queries**: Locate previous questions similar to a given query * **Get Error Solutions**: Discover how similar errors were resolved in past conversations * **List Recent Sessions**: View recent conversation sessions * **Extract Compact Summary**: Obtain a summary of a specific conversation session * **Analyze Tool Patterns**: Identify successful patterns of tool usage to improve workflows

Which integrations are available for this server?

Provides access to historical [Docker](/mcp/servers/integrations/docker) configuration solutions and authentication troubleshooting Enables finding information about [Git](/mcp/servers/integrations/git) operations during feature branch management and historical changes Allows retrieving historical solutions for [Kubernetes](/mcp/servers/integrations/kubernetes) deployment issues and container crashes Enables searching for past [React](/mcp/servers/integrations/react)-related solutions including infinite re-render loops and state management approaches Provides access to historical solutions for [Redis](/mcp/servers/integrations/redis) connection pooling problems Allows finding historical discussions on state management comparing [Redux](/mcp/servers/integrations/redux) with alternatives

claude-historian-mcp

A Model Context Protocol (MCP) server for searching your Claude Code (& Claude Desktop) conversation history. Find past solutions, track file changes, and learn from previous work.

npm version GitHub stars CodeRabbit Pull Request Reviews Claude TypeScript Node.js License: MIT

install

Requirements:

Claude Code

From shell:

claude mcp add claude-historian-mcp -- npx claude-historian-mcp

From inside Claude (restart required):

Add this to our global mcp config: npx claude-historian-mcp Install this mcp: https://github.com/Vvkmnn/claude-historian-mcp

From any manually configurable : (Cursor, Windsurf, etc.)

{ "mcpServers": { "claude-historian-mcp": { "command": "npx", "args": ["claude-historian-mcp"], "env": {} } } }

That's it; there is no as there are no external dependencies or local databases, only search algorithms.

However, in the unlikely event that you pull the wrong package / npx registry is out of date, you can force resolution issues in certain environments with:

npm install -g claude-historian-mcp

📦 renamed: This project was renamed from claude-historian to claude-historian-mcp. Existing users should update your install command and MCP config args to claude-historian-mcp.

Related MCP server: Claude AI Documentation Assistant

features

MCP server that gives Claude access to your conversation history. Fast search with smart prioritization.

Runs locally (with cool shades [⌐■_■]):

`search_conversations`

Search your conversation history for past solutions, discussions, and context.

[⌐■_■] search_conversations query=<query> > "How did we fix that Redis connection pooling nightmare?" > "Docker container keeps crashing on Kubernetes deployment" > "React infinite re-render loop - useEffect dependency hell"

[⌐■_■] "docker auth" | 2 results { "results": [{ "type": "assistant", "ts": "2h ago", "content": "Fixed Docker auth by updating registry credentials...", "project": "my-app", "score": 15, "ctx": { "filesReferenced": ["docker-compose.yml"], "toolsUsed": ["Edit", "Bash"] } }] }

`find_file_context`

Track modifications, edits, and discussions about specific files across sessions.

[⌐□_□] find_file_context filepath=<filepath> > "package.json changes that broke everything last month" > "When we accidentally committed .env to main branch" > "Authentication service refactor - before/after comparison"

[⌐□_□] "package.json" | 5 operations { "filepath": "package.json", "operations": [{ "type": "edit", "ts": "1d ago", "changes": ["added vitest dependency", "updated build script"], "ctx": { "filesReferenced": ["package.json", "vitest.config.ts"] } }] }

`get_error_solutions`

Find how you've resolved similar errors before, with code fixes and patterns.

[⌐×_×] get_error_solutions error_pattern=<error> > "MODULE_NOT_FOUND - the classic npm/yarn version mismatch" > "CORS preflight failing - but only on production Fridays?" > "Database deadlock during Black Friday traffic spike"

[⌐×_×] "ENOENT no such file" | 2 solutions { "solutions": [{ "pattern": "ENOENT: no such file or directory", "frequency": 3, "fixes": [{ "content": "Created missing directory", "code": ["mkdir -p ./dist"] }] }] }

`find_similar_queries`

Discover related questions you've asked before and their answers.

[⌐◆_◆] find_similar_queries query=<query> > "Database queries slower than my morning coffee brewing" > "How to implement error boundaries without losing sanity" > "State management: Redux vs Zustand vs just useState"

[⌐◆_◆] "typescript error handling" | 3 similar { "similar": [{ "query": "how to handle async errors in typescript", "similarity": 0.72, "ts": "3d ago", "project": "api-server" }] }

`list_recent_sessions`

Browse your recent Claude sessions with project context and accomplishments.

[⌐○_○] list_recent_sessions > "Tuesday debugging marathon: 9pm-3am flaky test hunt" > "Performance optimization sprint - reduced bundle 40%" > "The great TypeScript migration of 2024"

[⌐○_○] all | 3 sessions { "sessions": [{ "id": "68d5323b", "ts": "2h ago", "duration": 45, "messages": 128, "project": "my-app", "tools": ["Edit", "Bash", "Read"], "accomplishments": ["fixed auth bug", "added unit tests"] }] }

`find_tool_patterns`

Learn from your successful tool usage workflows and common sequences.

[⌐⎚_⎚] find_tool_patterns tool_name=<tool> > "Read → Edit → Bash combo for rapid prototyping" > "When I use Grep vs Task for different searches" > "Git operations during feature branch management"

[⌐⎚_⎚] "Edit" | 3 patterns { "tool": "Edit", "patterns": [{ "name": "Read → Edit → Bash", "uses": 7, "workflow": "Read → Edit → Bash", "practice": "Read file, edit, then run tests (7x successful)" }] }

`search_plans`

Search Claude Code plan files for past implementation approaches, decisions, and patterns.

[⌐▣_▣] search_plans query=<query> > "How did we architect the authentication system?" > "Database migration strategy from last refactor" > "API versioning approach we decided on"

[⌐▣_▣] "auth implementation" | 2 plans { "plans": [{ "file": "implement-oauth.md", "ts": "3d ago", "project": "my-app", "summary": "OAuth2 implementation with refresh tokens...", "decisions": ["chose PKCE flow", "JWT for access tokens"] }] }

`extract_compact_summary`

Get a concise summary of what was accomplished in a specific session.

[⌐◉_◉] extract_compact_summary session_id=<id> > "What did we accomplish in last session?" > "Summarize the authentication refactor work" > "Key decisions from yesterday's debugging"

[⌐◉_◉] extracting summary from my-app (68d5323b) { "session": { "id": "68d5323b", "ts": "2h ago", "duration": 45, "messages": 128, "project": "my-app", "tools": ["Edit", "Bash", "Read"], "files": ["src/auth.ts", "package.json"], "accomplishments": ["fixed auth bug", "added unit tests"], "decisions": ["chose JWT over sessions"] } }

methodology

How claude-historian works:

"docker auth" query | ├─> Parallel Processing (search.ts:157): 15 projects × 10 files concurrently | • Promise.allSettled for 6x speed improvement | • Early termination when sufficient results found | • Enhanced file coverage with comprehensive patterns | ├─> Enhanced Classification (search.ts:582): implementation → boost tool workflows | • Workflow detection for tool sequences (Edit → Read → Bash) | • Semantic boundary preservation (never truncate mid-function) | • Claude-optimized formatting with rich metadata | ├─> Smart Ranking (search.ts:637): | • "Edit workflow (7x successful)" (2h ago) ***** | • "Docker auth with context paths" (yesterday) **** | • "Container debugging patterns" (last week) *** | └─> Return Claude Code optimized results

Core optimizations:

parallel processing: Promise.allSettled for 6x speed improvement across projects and files
workflow detection: Captures tool sequences like "Edit → Read → Bash" patterns
enhanced file matching: Comprehensive path variations with case-insensitive matching
intelligent deduplication: Content-based deduplication preserving highest-scoring results
intelligent truncation: Never truncates mid-function or mid-error
Claude-optimized formatting: Rich metadata with technical content prioritization

Search strategies:

JSON streaming parser (parseJsonlFile): Reads Claude Code conversation files on-demand without full deserialization
LRU caching (messageCache): In-memory cache with intelligent eviction for frequently accessed conversations
TF-IDF inspired scoring (calculateRelevanceScore): Term frequency scoring with document frequency weighting for relevance
Query classification (classifyQueryType): Naive Bayes-style classification (error/implementation/analysis/general) with adaptive limits
Edit distance (calculateQuerySimilarity): Fuzzy matching for technical terms and typo tolerance
Exponential time decay (getTimeRangeFilter): Recent messages weighted higher with configurable half-life
Parallel file processing (getErrorSolutions): Concurrent project scanning with early termination for 0.8s response times
Workflow pattern recognition (getToolPatterns): Detects tool usage sequences and related workflows for learning
Enhanced file context (findFileContext): Multi-project search with comprehensive path matching
Content-aware truncation (smartTruncation): Intelligent content boundaries over arbitrary character limits
Technical content prioritization (BeautifulFormatter): Code blocks, errors, and file paths get full preservation
Query similarity clustering (findSimilarQueries): Semantic expansion and pattern grouping for related questions

File access:

Reads from: ~/.claude/conversations/
Zero persistent storage or indexing
Never leaves your machine

performance

See PERF.md for benchmarks, optimization history, and quality scores.

Current (v1.0.2): 4/7 tools at ≥4.0/5, targeting all 7. Focus: structured JSON output for Claude Code consumption.

development

git clone https://github.com/vvkmnn/claude-historian-mcp && cd claude-historian npm install && npm run build npm test

Package requirements:

Node.js: >=20.0.0 (ES modules support)
npm: >=10.0.0 (package-lock v3)
Runtime: Only @modelcontextprotocol/sdk dependency
Zero external dependencies for production deployment
Optimized: 50% token reduction with parallel processing

Development workflow:

npm run build # TypeScript compilation with executable permissions npm run dev # Watch mode with tsc --watch npm run start # Run the MCP server directly npm run lint # ESLint code quality checks npm run lint:fix # Auto-fix linting issues npm run format # Prettier formatting (src/) npm run format:check # Check formatting without changes npm run type-check # TypeScript validation without emit npm run test # Run help command + type check npm run prepublishOnly # Pre-publish validation (build + lint + format:check)

Git hooks (via Husky):

pre-commit: Auto-formats staged .ts files with Prettier and ESLint
pre-push: Runs full validation (format, lint, type-check, build) before push

Contributing:

Please fork the repository and create feature branches
Test with large conversation histories before submitting PRs
Follow TypeScript strict mode and MCP protocol standards

Learn from examples:

Official MCP servers for reference implementations
TypeScript SDK for best practices
Creating Node.js modules - NPM package development guide

desktop

Claude Desktop support is currently blocked by LevelDB locks and Electron sandboxing. You will still search Claude Desktop from Claude Code, but only when the Claude app is closed.

A DXT package and build is available for future compatibility; further investigations are ongoing. Feel free to test with it.

license

MIT

Claude Fauchet

Claude Fauchet (1744-1793), French Historian

Claude Historian