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

Chat History

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/.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 
npx cursor-chat-history-mcp link get-commit-links --hash 

# Manual linking
npx cursor-chat-history-mcp link manual --conversation  --commit

Database Locations

Override with CURSOR_DB_PATH or CURSOR_LINKS_DB_PATH.

Tool Reference

Core Tools Parameters

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

Git Linker Tools Parameters

**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

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