Cursor Chat History MCP

Connect your Cursor conversations to your git history.

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:

{
  "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

# 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

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']

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)

Development

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)
• [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 for git linker specification

License

MIT