The Cursor Conversations MCP Server enables AI assistants to locally access and analyze your Cursor chat history for personalized coding insights.
Access & Search: Browse conversations with filtering options, perform text-based searches, and discover related discussions based on files, folders, or languages.
Analyze & Extract: Generate analytics on usage patterns, extract code blocks, languages, and file references to identify recurring solutions and best practices.
Generate Content: Create personalized coding standards, project-specific documentation, and technical guides based on your actual development discussions.
Export & Visualize: Export chat data in JSON, CSV, or Graph formats for external analysis and visualization.
Privacy-Focused: Operates entirely locally without sending data to external services, ensuring your data remains private and under your control.
Supports accessing Cursor conversation data stored on Linux systems through the auto-detected database path.
Supports accessing Cursor conversation data stored on macOS systems through the auto-detected database path.
Enables analysis of React-specific conversations and code patterns to generate component guidelines and best practices.
Uses SQLite to access Cursor's conversation database for retrieving and analyzing development history.
Allows extraction of TypeScript coding standards and interface discussions from conversation history to create personalized guidelines.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Cursor Conversations MCP Server analyze my recent React conversations and suggest component patterns"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Connect your Cursor conversations to your git history.
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.
Related MCP server: AI Conversation Logger
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 was the context behind commit abc123?"
"Find the conversation that led to this fix"
"Show discussions about auth.ts from the last month""Find all debugging sessions about performance"
"Search conversations mentioning useState"
"List recent conversations in this project""Create TypeScript guidelines from my actual usage"
"Extract error handling patterns from my conversations"
"Summarize my React patterns from chat history"Tool | Purpose |
| Get conversations and commits related to a file |
| Find conversations linked to a commit |
| Find commits linked to a conversation |
| Manually link conversation ↔ commit |
Tool | Purpose |
| Browse with filters (project, keywords, files) |
| Get full conversation content |
| Multi-keyword and pattern search |
| Usage patterns, file activity, language stats |
100% local - No external services, no API keys
Your data stays on disk - SQLite databases only
Open source - Audit the code yourself
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
Large conversations aren't loaded directly into context. Instead:
Use get_file_context with keywords to find relevant conversations
Call get_conversation - writes to ~/.cursor-chat-history/context/conversations/<id>.md
Use Read/Grep tools to navigate the markdown file efficiently
# 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 | macOS | Windows | Linux |
Cursor chats |
|
|
|
Git links |
|
|
|
Context files |
| same | same |
Override with CURSOR_DB_PATH or CURSOR_LINKS_DB_PATH.
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)
git clone https://github.com/vltansky/cursor-chat-history-mcp
cd cursor-chat-history-mcp
yarn install
yarn buildAssistant | 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 |
Knowledge graph extraction - Extract entities and relationships from conversations (learn more)
Multi-agent support - Cline, Windsurf, Copilot Chat
Quality scoring - Prioritize conversations with solutions
Natural time filters - "last week", "yesterday"
Topic clustering - Group by detected themes
Semantic search - Find similar conversations via embeddings
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
MIT
Export chat data in various formats (JSON, CSV, Graph) for external analysis, visualization, or integration with other tools. TIP: Use filters.projectPath to export only project-specific conversations for focused analysis of a particular codebase. Use this to create datasets for machine learning, generate reports for stakeholders, prepare data for visualization tools like Gephi or Tableau, or backup chat data in structured formats.
Inputs: conversationIds, format, includeContent, includeRelationships, +3 more.
Extract specific elements from conversations such as file references, code blocks, programming languages, folder paths, metadata, or conversation structure. Use this to build knowledge bases, analyze code patterns, extract reusable snippets, understand project file usage, or prepare data for further analysis and documentation.
Inputs: conversationIds, elements, includeContext, groupBy, +2 more.
Retrieves the complete content of a specific Cursor conversation including all messages, code blocks, file references, title, and AI summary. WORKFLOW TIP: Use conversation IDs from list_conversations, search_conversations, or analytics breakdowns (files/languages arrays contain conversation IDs). Use summaryOnly=true to get enhanced summary data without full message content when you need to conserve context.
Inputs: conversationId (required), summaryOnly, outputMode.
Get comprehensive analytics and statistics about Cursor chats including usage patterns, file activity, programming language distribution, and temporal trends. BEST PRACTICE: Use projectPath parameter for project-specific analytics - this analyzes only conversations that worked on files in that project, providing much more relevant insights for understanding coding patterns, file usage, and development activity within a specific codebase. WORKFLOW TIP: Always include "files" and "languages" in breakdowns - these contain conversation IDs in their arrays that you can immediately use with get_conversation tool. Use includeConversationDetails=true when you need the full conversation ID list and basic metadata for follow-up analysis.
Inputs: scope, projectPath, recentDays, includeBreakdowns, +2 more.
Get system information and utilities for AI assistants. Provides current date, timezone, and other helpful context that AI assistants may not have access to. Use this when you need reference information for date filtering, time-based queries, or other system context.
Inputs: info.
Lists Cursor chats with summaries, titles, and metadata ordered by recency. HIGHLY RECOMMENDED: Use projectPath parameter to filter conversations by specific project/codebase - this dramatically improves relevance by finding conversations that actually worked on files in that project. Returns conversation IDs for use with get_conversation tool. WORKFLOW TIP: Start with projectPath filtering for project-specific analysis, then call get_conversation with specific IDs from results. Includes AI-generated summaries by default. Supports date range filtering (YYYY-MM-DD format).
Inputs: limit, minLength, hasCodeBlocks, keywords, +9 more.
Searches through Cursor chat content using exact text matching (NOT semantic search) to find relevant discussions. WARNING: For project-specific searches, use list_conversations with projectPath instead of this tool! This tool is for searching message content, not project filtering.
WHEN TO USE THIS TOOL:
Searching for specific technical terms in message content (e.g., "useState", "async/await")
Finding conversations mentioning specific error messages
Searching for code patterns or function names
WHEN NOT TO USE THIS TOOL:
❌ DON'T use query="project-name" - use list_conversations with projectPath instead
❌ DON'T search for project names in message content
❌ DON'T use this for project-specific filtering
Search methods (all use exact/literal text matching):
Simple text matching: Use query parameter for literal string matching (e.g., "react hooks")
Multi-keyword: Use keywords array with keywordOperator for exact matching
LIKE patterns: Advanced pattern matching with SQL wildcards (% = any chars, _ = single char)
Date range: Filter by message timestamps (YYYY-MM-DD format)
IMPORTANT: When using date filters, call get_system_info first to know today's date.
Examples: likePattern="%useState(%" for function calls, keywords=["typescript","interface"] with AND operator.
Inputs: query, keywords, keywordOperator, likePattern, +6 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
Most tools have distinct purposes, but there is some overlap between list_conversations and search_conversations, as both can be used to find conversations, which might cause confusion despite the detailed warnings. The other tools like export, extract, find_related, get, and analytics are clearly differentiated in their functions.
All tool names follow a consistent snake_case pattern with clear verb_noun structures (e.g., export_conversation_data, list_conversations, get_system_info). This uniformity makes the tool set predictable and easy to navigate for an agent.
With 8 tools, the count is well-suited for the server's purpose of managing and analyzing Cursor conversations. It covers core operations like listing, searching, retrieving, analyzing, exporting, and extracting, without being overwhelming or insufficient for the domain.
The tool set provides comprehensive coverage for conversation analysis, including CRUD-like operations (list, get, search) and advanced features (analytics, export, extraction, finding related). A minor gap is the lack of tools for modifying or deleting conversations, but this is likely intentional for a read-only analysis server.
Gives your AI assistant persistent memory and intelligence about your work patterns.
Persistent memory for AI assistants: store, search, and connect knowledge across conversations.
Bring your saved preferences, project decisions, and useful context into your next AI conversation.
Shared memory for AI coding agents. Save once, reuse from Cursor, Claude Code, Codex.
