Cursor Chat History MCP

🚀 Cursor Chat History MCP

Give AI assistants access to your Cursor chat history. This Model Context Protocol (MCP) server enables Cursor, Claude, and other AI assistants to read and analyze your Cursor chat data, providing personalized coding assistance based on your actual development patterns and history.

🚀 Quick Start

1. Configure MCP

Add the following to your .cursor/mcp.json:

{
  "mcpServers": {
    "cursor-chat-history": {
      "command": "npx",
      "args": ["-y", "--package=cursor-chat-history-mcp", "cursor-chat-history-mcp"]
    }
  }
}

2. Start Using

Here are some example commands you can use:

"Analyze my React conversations and create component guidelines"
"Find debugging patterns in my chat history"
"Generate TypeScript coding standards from my actual usage"
"What are the main themes in my recent coding discussions?"

✨ Features

What This Enables

You can ask your AI assistant to perform the following tasks:

• Analyze your chat history to understand your coding patterns and usage statistics.
• Generate project-specific rules based on your actual development discussions.
• Extract insights from past problem-solving sessions and find related conversations.
• Create documentation based on real conversations about your code.
• Export chat data for external analysis and visualization.
• Find and apply solutions you've already worked through.

Key Benefits

• Generate Personalized Rules: Create coding standards based on your actual development patterns, not generic best practices.
• Learn from Your History: Extract insights from past chats to improve future development.
• Context-Aware Assistance: Get help that's informed by your specific projects and coding style.
• Pattern Recognition: Identify recurring themes and solutions in your development work.

📦 Installation

For Development

git clone https://github.com/vltansky/cursor-chat-history-mcp
cd cursor-chat-history-mcp
yarn install
yarn build

For Use

The npx configuration mentioned above handles installation automatically.

💻 Usage Examples

Basic Usage

Once you've configured the MCP server, you can start interacting with your chat history using commands like those in the "Start Using" section above.

Advanced Usage

You can use the available tools to perform more complex operations. For example:

"Analyze my React conversations and create component guidelines"
"Find debugging patterns in my chat history"
"Generate TypeScript coding standards from my actual usage"
"What are the main themes in my recent coding discussions?"

📚 Documentation

Available Tools

Core Tools

• list_conversations: Browse conversations with filtering options and optional project relevance scoring.
• get_conversation: Retrieve full conversation content with code and file references.
• search_conversations: Enhanced search with multi-keyword, LIKE patterns, and text search.

Analytics & Data Extraction Tools

• get_conversation_analytics: Comprehensive analytics including usage patterns, file activity, programming language distribution, and temporal trends.
• find_related_conversations: Find conversations related by shared files, folders, languages, size, or temporal proximity.
• extract_conversation_elements: Extract files, code blocks, languages, metadata, and conversation structure with flexible grouping.
• export_conversation_data: Export chat data in JSON, CSV, or Graph formats for external analysis and visualization.

Tool Reference

Output Formats

All tools support JSON output formats via the outputMode parameter:

• json (default): Formatted JSON with proper indentation for readability.
• compact-json: Minified JSON without formatting for minimal size.

Core Tools

list_conversations

• limit (default: 10): Number of conversations to return.
• includeAiSummaries (default: true): Include AI-generated summaries for efficient browsing.
• projectPath: Filter by project path.
• includeRelevanceScore (default: false): Include relevance scores when filtering by projectPath.
• hasCodeBlocks: Filter conversations with/without code.
• keywords: Search by keywords.
• filePattern: Filter by file pattern.

get_conversation

• conversationId (required): Conversation to retrieve.
• summaryOnly (default: false): Get enhanced summary without full content to save context.
• includeMetadata (default: false): Include additional metadata.

search_conversations - Enhanced search with multiple methods

• Simple Query: query - Basic text search (backward compatible).
• Multi-keyword: keywords array with keywordOperator ('AND'/'OR').
• LIKE Patterns: likePattern - SQL LIKE patterns (% = any chars, _ = single char).
• searchType (default: 'all'): 'all', 'project', 'files', 'code'.
• maxResults (default: 10): Maximum results.
• includeCode (default: true): Include code blocks.

Analytics & Data Extraction Tools

get_conversation_analytics

• scope (default: 'all'): 'all', 'recent', 'project'.
• projectPath: Focus on specific project (required when scope='project').
• recentDays (default: 30): Time window for recent scope.
• includeBreakdowns (default: ['files', 'languages']): Analysis types: 'files', 'languages', 'temporal', 'size'.

find_related_conversations

• referenceConversationId (required): Starting conversation.
• relationshipTypes (default: ['files']): 'files', 'folders', 'languages', 'size', 'temporal'.
• maxResults (default: 10): Number of results.
• minScore (default: 0.1): Minimum similarity score (0-1).
• includeScoreBreakdown (default: false): Show individual relationship scores.

extract_conversation_elements

• conversationIds: Specific conversations (optional, processes all if empty).
• elements (default: ['files', 'codeblocks']): 'files', 'folders', 'languages', 'codeblocks', 'metadata', 'structure'.
• includeContext (default: false): Include surrounding message text.
• groupBy (default: 'conversation'): 'conversation', 'element', 'none'.
• filters: Filter by code length, file extensions, or languages.

export_conversation_data

• conversationIds: Specific conversations (optional, exports all if empty).
• format (default: 'json'): 'json', 'csv', 'graph'.
• includeContent (default: false): Include full message text.
• includeRelationships (default: false): Calculate file/folder connections.
• flattenStructure (default: false): Flatten for CSV compatibility.
• filters: Filter by size, code blocks, or project path.

Database Paths

Auto-detected locations:

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
• Windows: %APPDATA%/Cursor/User/globalStorage/state.vscdb
• Linux: ~/.config/Cursor/User/globalStorage/state.vscdb

🔧 Technical Details

• Supports both legacy and modern Cursor conversation formats.
• Uses SQLite to access Cursor's chat database.
• Close Cursor before running to avoid database lock issues.
• Conversations filtered by size (>1000 bytes) to exclude empty ones.
• Uses ROWID for chronological ordering (UUIDs are not chronological).

How It Works

The system uses a summary-first approach for efficiency:

Data Access Process

1. Full Content Analysis: All tools access complete chat data, including complete message text, code and file references, conversation metadata, and AI-generated summaries.
2. Smart Result Delivery: Different tools provide focused outputs. For example, list_conversations returns conversation summaries, search_conversations returns summaries with relevance scores, and analytics tools extract insights and patterns.
3. Summary-First Results: Most tools return conversation summaries, titles, key metadata, AI-generated summaries (when available), and relevant scores and analytics.

Why This Design?

• Context Efficiency: Avoids overwhelming AI assistants with full message content.
• Performance: Summaries are much smaller and faster to process.
• Discoverability: Users can quickly scan results to identify relevant conversations.
• Deep Dive When Needed: Use get_conversation for full content of specific conversations.

🤝 Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add tests if applicable.
5. Submit a pull request.

📄 License

This project is licensed under the MIT license.