Submit
Vvkmnn

claude-historian-mcp

Community Vvkmnn
Updated

🤖 An MCP server for surfacing useful Claude Code conversation history

claude-historian-mcp

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 mcp.json: (Cursor, Windsurf, etc.)

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

That's it; there is no npm install required 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.

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:

Search strategies:

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:

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

MCP Server · Populars

MCP Server · New