cc-session-search

This MCP server provides tools to search, list, and analyze Claude Code conversation history. It exposes capabilities such as listing projects and sessions, retrieving recent conversations, analyzing messages with role filtering, performing term searches with context windows, and obtaining detailed message content or summarized discussions. You can query across multiple Claude Code projects stored under the standard Claude Code setup (typically within the user’s ~/.claude/projects directory) and apply filters like date ranges, project scope, and role filters to tailor results. The included tools are designed to minimize token usage through metadata-first responses and to support cross-project search and analysis.

To use the server, call the provided MCP endpoints for the supported methods: list_projects(), list_sessions(project_name, days_back), list_recent_sessions(days_back, project_filter), analyze_sessions(days_back, role_filter, include_tools, project_filter), search_conversations(query, days_back, context_window, case_sensitive, project_filter), and get_message_details(session_id, message_indices). Each tool returns structured data (e.g., lists of sessions, messages, or summarized content) suitable for integration with your client or UI. The server is built with the official MCP Python SDK and emphasizes efficient response handling, including content truncation where needed, and a metadata-first approach to minimize token usage across requests.

Typical use cases include: quickly listing all Claude Code projects and their activity, drilling into a project to view recent sessions, filtering conversations by role (user/system/assistant) for analysis, performing targeted searches for terms within specific contexts and time ranges, and retrieving complete message content for particular sessions for deeper inspection or reporting.

Prerequisites:

• Python 3.13+ installed
• MCP runtime (as required by your environment) with access to Claude Code projects at ~/.claude/projects
• Optional: uv (uvicorn) for Python-based servers if not already installed in your environment

Installation steps:

1. Install dependencies (if using uv):

uv sync

2. Prepare the server files:

• Ensure you have the server.py file and the MCP server code for cc-session-search placed in a directory, e.g., /path/to/cc-session-search
• Confirm Claude Code projects are accessible under ~/.claude/projects

3. Run the server (development/testing):

uv run python server.py

4. Register the MCP server in Claude Code configuration (example):

{
  "servers": {
    "cc-session-search": {
      "command": ["uv", "run", "python", "server.py"],
      "cwd": "/path/to/cc-session-search"
    }
  }
}

5. Verify the server is reachable via the MCP interface and begin using the available tools.

Tips and considerations:

• The server expects Claude Code project data to be available under the standard path (~/.claude/projects). Ensure read permissions are set accordingly.
• Adjust the cwd (working directory) in the MCP config to the actual location of your cc-session-search project when deploying.
• If you encounter token limits or long responses, rely on the server's built-in content truncation and metadata-first responses to optimize payloads.
• You can filter results by days_back (e.g., 1, 7, 30) and by project when using list_sessions, list_recent_sessions, and analyze/search tools.
• When upgrading, verify compatibility with MCP 1.2.0+ and Python 3.13+ as specified in the requirements.
• If you plan to run in production, consider containerization (Docker) or a process manager to ensure uptime and proper logging.