Chronicle MCP

by Leviathan0x0

464 downloads

Not rated

GitHub

About

Chronicle MCP is a high-performance, universal local chat history archive connector designed specifically for Model Context Protocol (MCP) clients like Cursor, Claude Code, and daily development environments. Built natively in Python, it serves as an intelligent local storage and

Details

Author: Leviathan0x0
Downloads: 464
Categories: AI, Productivity

- Format normalization engine for ChatGPT, Claude, generic JSON, and Markdown.
- Context token optimization with code block summarization and length limiting.
- Six versatile tools: search, read, sync, compile insights, maintain storage.
- Cross-platform path resolution for macOS, Windows, and Linux.
- Native IDE integration with fallback engine for emerging platforms.
- Structural split engine for large conversation JSON exports.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Chronicle MCP

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

From the repository

Install the server and run chronicle to launch the stdio transport for MCP clients. Use chronicle add to configure IDE integrations (Cursor, Claude Code, VS Code, Trae) with automatic path resolution, and chronicle split to break monolithic chat exports into individual files. Customize the storage folder with --chats-folder.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "chronicle mcp": {
            "chronicle-mcp": {
                "command": "uvx",
                "args": [
                    "chronicle-mcp-server"
                ]
            }
        }
    }
}

McpServers

{
    "chronicle-mcp": {
        "command": "uvx",
        "args": [
            "chronicle-mcp-server"
        ]
    }
}

Chronicle: Universal Chat Connector Model Context Protocol Server

Chronicle is a production-grade Model Context Protocol (MCP) server designed to sync, clean, format, and index local artificial intelligence chat transcripts. By bridging the gap between local editor history and large language model contexts, Chronicle allows agents to search, compare, retrieve, and reference past conversation logs. It features optimized token-saving heuristics that compress code blocks and limit message lengths, reducing context window utilization by up to 40 percent.

Key Architectural Capabilities

Format Normalization Engine

AI providers and editor clients save conversation logs in diverse formats. Chronicle normalizes these structures into a standard role-and-content message format: ChatGPT Exports: ChatGPT exports conversation histories in recursive mapping node structures. Chronicle traverses and flattens these maps, sorts messages chronologically by creation timestamp, and extracts the plain-text message threads. Claude Exports: Claude structures messages as flat lists nested under the chat_messages field. Chronicle parses these lists, maps custom sender roles (such as human and assistant) to standard roles, and cleans the text strings. Generic and Markdown Formats: Chronicle includes parsers for flat JSON message lists (such as Cline or Continue) and structured Markdown logs (mapping headers like User and Assistant to message boundaries).
Context Token Optimization
Large chat logs can quickly exhaust context windows and increase API costs. Chronicle implements proactive token-saving mechanisms: Code Block Summarization: Automatically replaces verbose code blocks with metadata summaries indicating the programming language and line count. This behavior can be disabled on demand to read full code snippets. Length Limiting: Truncates extremely long individual messages at a configurable character threshold, appending a notice that the user can re-run the tool with expanded limits if necessary.
---

Command Line Interface Mechanics

The cli.py file serves as the system's entry point, registering a unified chronicle command on the system path via the pyproject.toml configuration (chronicle = "cli:main"). The CLI contains several advanced capabilities designed for platform compatibility and developer ergonomics:

1. Unified Chronicle Global Command
When run without subcommands, the chronicle command launches the stdio transport server for MCP clients:
chronicle
It accepts options like --chats-folder to configure custom storage directories, and exposes the subcommands add and split.
2. Cross-Platform Path Resolution Rules
The CLI implements path resolution logic using Python's sys.platform and pathlib.Path to match standard OS conventions for user directories: macOS (Darwin): Resolves configurations to the user's home Library folder, typically under ~/Library/Application Support/. Windows (Win32): Leverages the %APPDATA% environment variable, falling back to ~/AppData/Roaming/ if the variable is not set. Linux: Follows the XDG base directory specification, resolving to ~/.config/.

3. Native IDE Integration and Fallback Engine

The CLI wrapper provides out-of-the-box support for leading AI-assisted development tools and editors: Cursor: Reads and writes configurations to ~/.cursor/mcp.json. Claude Code: Integrates with ~/.claude.json. VS Code (Cline/RooCode/Continue): Standardizes pathing across platforms: macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json Trae: Resolves configuration to: macOS: ~/Library/Application Support/Trae/mcp.json Windows: %APPDATA%/Trae/mcp.json Linux: ~/.config/Trae/mcp.json Dynamic Fallback Engine: For emerging platforms (such as Kiro, MiniMax, Qwen Code, Grok Build, or Antigravity), the CLI employs a fallback search pattern. It first checks for a user home dot-directory configuration (such as ~/.<app_name>/mcp.json). If that directory is missing, it creates the app-specific configuration in the standard application support folder for the respective platform (e.g. ~/Library/Application Support/<app_name>/mcp.json on macOS).
4. Prevent ENOENT Errors with shutil.which
Host clients (like Claude Desktop or Cline) spawn MCP servers within isolated subprocesses that often do not inherit the user's login shell environment variables (such as custom paths defined in .bashrc or .zshrc). Attempting to call uvx or global scripts directly can raise an ENOENT connection error if the host application cannot find the executable. To solve this, the chronicle add utility uses Python's shutil.which("uvx") to scan the host machine path during configuration. It resolves the absolute system path of uvx (such as /opt/homebrew/bin/uvx or /usr/local/bin/uvx) and writes this absolute path directly to the IDE's JSON configuration file.
5. Structural Split Engine Subcommand
Users downloading conversational archives from ChatGPT or Claude are often provided with a single monolithic JSON file (such as conversations.json) containing hundreds of distinct threads. The chronicle split subcommand parses these large payloads and splits them into individual JSON files: Automatically detects the schema format (nested conversation trees or flat lists). Identifies thread titles using key fallback fields (checking title, name, and chat_title). Sanitizes file names to remove platform-forbidden characters (such as /, \, , ?, :, ", <, >, and |) and limits length. Resolves filename collisions by appending incremental numeric suffixes.

chronicle split /path/to/conversations.json --out /path/to/output_directory

6. Global Chats Folder Configuration

By default, Chronicle stores processed archives in ~/.chronicle/chats. You can configure a custom global storage folder using the --chats-folder parameter:

chronicle --chats-folder /path/to/custom/chats

This saves the target path to a local settings file (~/.chronicle_settings.json), allowing you to centralize your archives across multiple development environments.

---

Tool Reference Catalog

Chronicle consolidates its behaviors into 6 versatile, parameterized tools. This design avoids cognitive overhead for client AI models while preserving the server's complete feature set.

…

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

Chronicle: Universal Chat Connector Model Context Protocol Server

Key Architectural Capabilities

Format Normalization Engine

Context Token Optimization

Command Line Interface Mechanics

1. Unified Chronicle Global Command

2. Cross-Platform Path Resolution Rules

3. Native IDE Integration and Fallback Engine

4. Prevent ENOENT Errors with shutil.which

5. Structural Split Engine Subcommand

6. Global Chats Folder Configuration

Tool Reference Catalog

Install

More like this

Time

Context 7

1Panel

🔎 GPT Researcher

Serena

FastMCP v2 🚀