Cursor Chat History MCP server

The Cursor Chat History MCP is a Model Context Protocol server that allows AI assistants to access and analyze your Cursor chat history. This enables personalized coding assistance based on your actual development patterns, helping you generate project-specific rules and extract insights from past problem-solving sessions.

Installation

Setting Up MCP

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

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

This configuration allows Cursor to automatically install and run the MCP server when needed.

Usage

Basic Prompts

You can start using the MCP server by asking your AI assistant questions like:

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

Available Tools

Core Tools

The MCP server provides several tools for accessing and analyzing your chat history:

• List Conversations: Browse conversations with filtering options
• Get Conversation: Retrieve full conversation content with code and file references
• Search Conversations: Enhanced search with multi-keyword support

Analytics & Data Extraction Tools

• Get Conversation Analytics: View usage patterns, file activity, and programming language distribution
• Find Related Conversations: Discover conversations related by shared files or other attributes
• Extract Conversation Elements: Pull out files, code blocks, and other elements
• Export Conversation Data: Export chat data in various formats for external analysis

Common Use Cases

Generate Coding Rules

"Create TypeScript interface naming conventions from my conversations"
"Extract error handling patterns and create guidelines"
"Find all my discussions about testing and create best practices"

Extract Best Practices

"Show me how I typically use React hooks in my projects"
"Find patterns in my state management discussions"
"Analyze my class inheritance usage and create guidelines"

Advanced Analysis

"Find conversations where I discussed specific functions or patterns"
"Search for file-specific discussions across my projects"
"Compare how I've approached similar problems over time"

Create Project Documentation

"Generate API documentation from my service discussions"
"Create technical docs from my auth module conversations"

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 Configuration

list_conversations

• limit (default: 10) - Number of conversations to return
• includeAiSummaries (default: true) - Include AI-generated summaries
• projectPath - Filter by project path
• includeRelevanceScore (default: false) - Include relevance scores when filtering
• 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
• includeMetadata (default: false) - Include additional metadata

search_conversations

• query - Basic text search
• keywords - Array with keywordOperator ('AND'/'OR')
• 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 Configuration

get_conversation_analytics

• scope (default: 'all') - 'all', 'recent', 'project'
• projectPath - Focus on specific project
• recentDays (default: 30) - Time window for recent scope
• includeBreakdowns (default: ['files', 'languages']) - Analysis types

find_related_conversations

• referenceConversationId (required) - Starting conversation
• relationshipTypes (default: ['files']) - Types of relationships to consider
• maxResults (default: 10) - Number of results
• minScore (default: 0.1) - Minimum similarity score (0-1)

extract_conversation_elements

• conversationIds - Specific conversations (optional)
• elements (default: ['files', 'codeblocks']) - Elements to extract
• includeContext (default: false) - Include surrounding message text
• groupBy (default: 'conversation') - How to group results

export_conversation_data

• conversationIds - Specific conversations (optional)
• format (default: 'json') - 'json', 'csv', 'graph'
• includeContent (default: false) - Include full message text
• includeRelationships (default: false) - Calculate connections
• flattenStructure (default: false) - Flatten for CSV compatibility

Privacy & Security

The MCP server prioritizes your privacy:

• 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

The system uses a summary-first approach for efficiency:

1. Full Content Analysis: All tools access complete chat data
2. Smart Result Delivery: Different tools provide focused outputs
3. Summary-First Results: Most tools return conversation summaries and metadata

This approach allows you to efficiently browse and analyze your chat history, then dive deeper only into conversations that matter for your current task.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.