# Cursor Chat History MCP
**Connect your Cursor conversations to your git history.**
<a href="https://glama.ai/mcp/servers/@vltansky/cursor-conversations-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@vltansky/cursor-conversations-mcp/badge" alt="Cursor Conversations Server MCP server" />
</a>
## Why?
You make a commit. Weeks later you wonder: *"Why did I write it this way?"*
The git message says `fix auth bug` but the real context - the debugging session, the alternatives considered, the AI suggestions - lives in a Cursor conversation you'll never find again.
This MCP server automatically links your Cursor conversations to git commits. When you revisit code, the AI assistant can pull up the original discussion.
## Quick Start
Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"cursor-chat-history": {
"command": "npx",
"args": ["-y", "--package=cursor-chat-history-mcp", "cursor-chat-history-mcp"]
}
}
}
```
That's it. Hooks install automatically on first use.
## What You Can Do
### Find Context for Code
```
"What was the context behind commit abc123?"
"Find the conversation that led to this fix"
"Show discussions about auth.ts from the last month"
```
### Search Your Chat History
```
"Find all debugging sessions about performance"
"Search conversations mentioning useState"
"List recent conversations in this project"
```
### Extract Patterns
```
"Create TypeScript guidelines from my actual usage"
"Extract error handling patterns from my conversations"
"Summarize my React patterns from chat history"
```
## Available Tools
### Git Linker
| Tool | Purpose |
|------|---------|
| `get_file_context` | Get conversations and commits related to a file |
| `get_commit_conversations` | Find conversations linked to a commit |
| `list_conversation_commits` | Find commits linked to a conversation |
| `link_conversation_commit` | Manually link conversation ↔ commit |
### Chat History
| Tool | Purpose |
|------|---------|
| `list_conversations` | Browse with filters (project, keywords, files) |
| `get_conversation` | Get full conversation content |
| `search_conversations` | Multi-keyword and pattern search |
| `get_conversation_analytics` | Usage patterns, file activity, language stats |
## Privacy
- **100% local** - No external services, no API keys
- **Your data stays on disk** - SQLite databases only
- **Open source** - Audit the code yourself
---
## How It Works
Hooks are installed automatically when the MCP server starts:
- **Cursor hooks** (`~/.cursor/hooks.json`) - capture file edits and session ends
- **Git post-commit hook** (current repo) - link commits to conversations
When you commit, the system finds related conversations using:
- **File overlap (70%)**: Commits touching files discussed in conversations
- **Recency (30%)**: Conversations from the last 14 days
### Efficient Context Retrieval
Large conversations aren't loaded directly into context. Instead:
1. Use `get_file_context` with `keywords` to find relevant conversations
2. Call `get_conversation` - writes to `~/.cursor-chat-history/context/conversations/<id>.md`
3. Use Read/Grep tools to navigate the markdown file efficiently
### CLI Commands
```bash
# Query links
npx cursor-chat-history-mcp link list-conversation-links --conversation <id>
npx cursor-chat-history-mcp link get-commit-links --hash <commit-hash>
# Manual linking
npx cursor-chat-history-mcp link manual --conversation <id> --commit <hash>
```
## Database Locations
| Database | macOS | Windows | Linux |
|----------|-------|---------|-------|
| Cursor chats | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` | `%APPDATA%/Cursor/...` | `~/.config/Cursor/...` |
| Git links | `~/Library/Application Support/CursorChatHistory/links.sqlite` | `%APPDATA%/CursorChatHistory/...` | `~/.local/share/CursorChatHistory/...` |
| Context files | `~/.cursor-chat-history/context/conversations/` | same | same |
Override with `CURSOR_DB_PATH` or `CURSOR_LINKS_DB_PATH`.
## Tool Reference
<details>
<summary>Core Tools Parameters</summary>
**`list_conversations`**
- `limit` (default: 10) - Number of results
- `projectPath` - Filter by project
- `keywords` - Search keywords
- `hasCodeBlocks` - Filter by code presence
**`get_conversation`**
- `conversationId` (required) - Conversation ID
- `summaryOnly` - Return summary only (saves context)
**`search_conversations`**
- `query` - Text search
- `keywords` + `keywordOperator` ('AND'/'OR') - Multi-keyword
- `likePattern` - SQL LIKE patterns
**`get_conversation_analytics`**
- `scope` - 'all', 'recent', 'project'
- `projectPath` - Filter by project
- `includeBreakdowns` - ['files', 'languages', 'temporal', 'size']
</details>
<details>
<summary>Git Linker Tools Parameters</summary>
**`get_file_context`**
- `filePath` (required) - File to get context for
- `keywords` - Filter by keywords (e.g., `["JWT", "auth"]`) - returns matching excerpts
- `limit` - Max results (default: 5)
**`list_conversation_commits`**
- `conversationId` - Filter by conversation
- `projectPath` - Filter by project
- `filePath` - Filter by file
**`get_commit_conversations`**
- `commitHash` (required) - Git commit hash
**`link_conversation_commit`**
- `conversationId` (required)
- `commitHash` (required)
- `confidence` - Link confidence (0-1)
</details>
## Development
```bash
git clone https://github.com/vltansky/cursor-chat-history-mcp
cd cursor-chat-history-mcp
yarn install
yarn build
```
## Supported AI Assistants
| Assistant | Status | Notes |
|-----------|--------|-------|
| **Cursor** | ✅ Full | Chat, Composer, Agent modes |
| **Claude Code** | ✅ Full | VS Code extension |
| **Cline/Roo/Kilo** | ✅ Full | JSON task-based storage |
| **Windsurf** | ✅ Full | SQLite (same pattern as Cursor) |
| **GitHub Copilot Chat** | ✅ Full | VS Code native |
## Roadmap
- [ ] **Knowledge graph extraction** - Extract entities and relationships from conversations ([learn more](docs/knowledge-graphs.md))
- [x] **Multi-agent support** - Cline, Windsurf, Copilot Chat
- [x] **Quality scoring** - Prioritize conversations with solutions
- [x] **Natural time filters** - "last week", "yesterday"
- [x] **Topic clustering** - Group by detected themes
- [ ] **Semantic search** - Find similar conversations via embeddings
## Technical Notes
- Supports legacy and modern Cursor conversation formats
- Uses ROWID for chronological ordering (UUIDs aren't chronological)
- Close Cursor to avoid database lock issues
- See [docs/SPEC.md](docs/SPEC.md) for git linker specification
## License
MIT
