Cursor Conversations MCP Server

Cursor Chat History MCP

Give AI assistants access to your Cursor chat history.

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

What This Enables

Ask your AI assistant to:

• 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.

Quick Start

1. Configure MCP

Add to your .cursor/mcp.json:

2. Start Using

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

Common Use Cases

Generate Coding Rules

Extract Best Practices

Advanced Analysis

Create Project Documentation

Learn from Past Solutions

Data Analysis & Insights

Privacy & Security

• Runs locally - Your chat data never leaves your machine
• No external services - Direct access to your local Cursor database
• No API keys required - No data sharing with external services
• Full control - You decide what data to access and when

How It Works

Summary-First Approach for Efficiency

The entire system is designed to be both powerful and context-efficient:

Data Access Process

1. Full Content Analysis: All tools access complete chat data including:
   • Complete message text and code blocks
   • File references and folder paths
   • Conversation metadata and titles
   • AI-generated summaries
2. Smart Result Delivery: Different tools provide focused outputs:
   • list_conversations: Returns conversation summaries with titles and metadata
   • search_conversations: Searches full content but returns only summaries with relevance scores
   • Analytics tools: Extract insights and patterns without overwhelming detail
3. Summary-First Results: Most tools return:
   • Conversation summaries and titles
   • Key metadata (files, folders, message count)
   • AI-generated summaries when available
   • 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

This approach lets you efficiently browse, search, and analyze your chat history, then dive deep only into conversations that matter for your current task.

Installation

For Development

For Use

The npx configuration above handles installation automatically.

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 Notes

• 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)

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

MIT