Claude Historian▌

# claude-historian-mcp An [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for searching your [Claude Code](https://docs.anthropic.com/en/docs/claude-code) conversation history. Find past solutions, track file changes, and learn from previous work.
 [](https://www.npmjs.com/package/claude-historian-mcp) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](#) [](https://github.com/Vvkmnn/claude-historian-mcp)  --- ## install **Requirements:** [](https://claude.ai/code) **From shell:** ```bash 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.) ```json { "mcpServers": { "claude-historian-mcp": { "command": "npx", "args": ["claude-historian-mcp"], "env": {} } } } ``` There is **no `npm install` required** -- no external dependencies or local databases, only search algorithms. However, if `npx` resolves the wrong package, you can force resolution with: ```bash 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`. ## [skill](.claude/skills/claude-historian) Optionally, install the skill to teach Claude when to proactively use historian: ```bash npx skills add Vvkmnn/claude-historian-mcp --skill claude-historian --global # Optional: add --yes to skip interactive prompt and install to all agents ``` This makes Claude automatically check your history before web searches, when encountering errors, or at session start. The MCP works without the skill, but the skill improves discoverability. ## [plugin](https://github.com/Vvkmnn/claude-emporium) For automatic history search with hooks and commands, install from the [claude-emporium](https://github.com/Vvkmnn/claude-emporium) marketplace: ```bash /plugin marketplace add Vvkmnn/claude-emporium /plugin install claude-historian@claude-emporium ``` The **claude-historian** plugin provides: **Hooks** (targeted, zero overhead on success): - Before WebSearch/WebFetch → Check `find_similar_queries` - Before EnterPlanMode → Check `search_plans` - Before Task agents → Check `find_tool_patterns` - After Bash errors → Check `get_error_solutions` **Command:** `/historian-search ` Requires the MCP server installed first. See the emporium for other Claude Code plugins and MCPs. ## features [MCP server](https://modelcontextprotocol.io/) 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= > "How did we fix that Redis connection pooling nightmare?" > "Docker container keeps crashing on Kubernetes deployment" > "React infinite re-render loop - useEffect dependency hell" ``` ```json [⌐■_■] 📜 "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= > "package.json changes that broke everything last month" > "When we accidentally committed .env to main branch" > "Authentication service refactor - before/after comparison" ``` ```json [⌐□_□] 📜 "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= > "MODULE_NOT_FOUND - the classic npm/yarn version mismatch" > "CORS preflight failing - but only on production Fridays?" > "Database deadlock during Black Friday traffic spike" ``` ```json [⌐×_×] 📜 "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= > "Database queries slower than my morning coffee brewing" > "How to implement error boundaries without losing sanity" > "State management: Redux vs Zustand vs just useState" ``` ```json [⌐◆_◆] 📜 "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" ``` ```json [⌐○_○] 📜 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= > "Read → Edit → Bash combo for rapid prototyping" > "When I use Grep vs Task for different searches" > "Git operations during feature branch management" ``` ```json [⌐⎚_⎚] 📜 "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= > "How did we architect the authentication system?" > "Database migration strategy from last refactor" > "API versioning approach we decided on" ``` ```json [⌐▣_▣] 📜 "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"] }] } ``` #### `search_config` Search .claude configuration files (rules, skills, agents, CLAUDE.md) for guidance and patterns. ``` [⌐◈_◈] 📜 search_config query= > "What are my rules about minimalism and code quality?" > "Find the systematic debugging skill documentation" > "Search for test-driven development guidelines" ``` ```json [⌐◈_◈] 📜 "verify everything" | 2 results { "results": [{ "type": "assistant", "ts": "1/31/2026", "content": "# Verify Everything ## Rule Every claim must be anchored to evidence...", "file": "/Users/v/.claude/rules/verify.md", "category": "global-rules", "score": 34 }] } ``` #### `search_tasks` Search task manageme ---