Skip to content
MCP server

Chronicle MCP

Local BM25 search over your Cursor, Claude, ChatGPT and Cline chat history

Runs locallyStatus and history
Install
Pricing
Free
Platforms
CLI, self-hosted, macOS
Runs
Locally
Version
1.6.2
Listing updated
1 day ago

About Chronicle MCP

Chronicle MCP is a free MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.

Chronicle MCP keeps a private, offline archive of past AI conversations so an agent can recall earlier work without you pasting it back in. It syncs transcripts from editors and exports, normalises them into one role-and-content format, and indexes them on your machine. The README says there is no cloud service, account or API key, and the archive defaults to a .chronicle folder in your home directory.

The search design is specific. Long conversations are split into chunks when there is a gap of more than 30 minutes or when vocabulary similarity between message groups falls, and chunks are scored with Okapi BM25 using a strong length penalty so rambling logs do not drown short bug fixes. Saved handoff receipts, which record modified paths, commitments, skipped tests and next actions, are bubbled to the top of results. To save context, code blocks are summarised by language and line count and long messages are truncated, which the README says cuts token use by up to 40 percent.

Version 1.6.2 added documented tools with safety annotations, real error results, a recall_past_work prompt and two resources. It runs through uvx, pip or Docker, with an interactive setup wizard that edits client configs.

Install

Run in a terminal

claude mcp add chronicle-mcp -- uvx chronicle-mcp-server

Add to claude_desktop_config.json

{
  "mcpServers": {
    "chronicle-mcp": {
      "command": "uvx",
      "args": [
        "chronicle-mcp-server"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "chronicle-mcp": {
      "command": "uvx",
      "args": [
        "chronicle-mcp-server"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Configuration

  • CHRONICLE_BASE_DIRFolder for the chat archive and search index. Defaults to ~/.chronicle (or the folder saved with chronicle --chats-folder).
  • TRANSCRIPTS_DIROverride folder scanned by sync_workspace_data(source_type='agent_transcripts'). Defaults to each editor's own transcript folder.

Tools this server provides (2)

Taken from the project documentation; the running server may differ.

maintain_storage
Maintain the archive and report capabilities.
sync_workspace_data
Sync transcripts from editor workspaces into the archive.

What it does

Local archive
Indexes chat transcripts on your own disk with no account or key.
Format normalisation
Parses ChatGPT and Claude exports plus Cline, Continue and Markdown logs.
BM25 search
Chunked conversation search with a strong length penalty.
Handoff receipts
Saved agent state files rank at the top of results.
Token savings
Summarises code blocks and truncates long messages.
Setup wizard
A terminal wizard splits exports and writes client configuration.

Good for

  • Recall how a bug was fixed in an earlier Cursor session
  • Search old ChatGPT or Claude exports for a decision
  • Hand over agent state between sessions with a receipt
  • Reduce repeated context pasted into new chats

Pricing

Free

Free local server; no account or API key

Chronicle MCP FAQ

Does my chat history leave my machine?

No. The README says the archive and index stay on disk with no cloud service.

Which tools' chats can it read?

Cursor, Claude, ChatGPT and Cline, plus generic JSON and Markdown logs.

How do I run it?

Through uvx chronicle-mcp-server, pip, or a Dockerfile.

How many tools does it have?

The 1.6.1 notes list 8 tools plus the start_session prompt.

Is Chronicle MCP free?

Yes. Chronicle MCP is free to use.

How do I add Chronicle MCP to Claude Code?

Run this command in your terminal: claude mcp add chronicle-mcp -- uvx chronicle-mcp-server

What are the best alternatives to Chronicle MCP?

The closest alternatives to Chronicle MCP are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to Chronicle MCP

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools