Journal MCP

Every Claude Code session opens cold and is up to speed in 30 seconds. No re-explaining.

A local MCP for Claude Code + a CLAUDE.md rule. Together they turn each project's *JOURNAL.md file into a single source of truth that survives compaction, account switches, and machine wipes. Claude auto-maintains it: reads at session start, appends after every shipped piece of work, updates Current state / Roadmap / Handoff sections as things change.

The next Claude session opens the project and is instantly aware of past decisions, current state, and what to do next.

What Journal MCP does — and does NOT do

| Does | Does NOT | |---|---| | Indexes *JOURNAL.md files in folders you point it at | Does not read any file other than *JOURNAL.md matches | | Lets Claude read / append / search / update sections | Does not write anywhere outside the journal files you create | | Scaffolds new journals with standard sections | Does not create journals without you asking | | Optionally pushes a copy to your Google Drive via rclone | Does not upload anywhere without your explicit journal_backup_to_drive() call | | Installs a CLAUDE.md rule (with confirm=True) | Does not modify CLAUDE.md until you opt in | | Stores an index DB at ~/.journal/index.sqlite | Does not phone home, no telemetry, no analytics | | Runs locally on your machine via Python stdio | Does not require any login, license key, or hosted service |

Trust posture: your journals live in your project folders. The MCP indexes them; that's it. Uninstall removes one .mcp.json entry, one CLAUDE.md section, and ~/.journal/. Your .md files are yours, untouched.

Install

See INSTALL.md. Paste it into a Claude Code chat and ask Claude to walk you through. 60 seconds.

The product = MCP + Rule

MCP tools (this folder's server.py): read / append / search / update / handoff
CLAUDE.md rule (installed via journal_install_rule()): tells every Claude session to USE the tools — read at start, append after shipped work, update state as it moves

Without the rule, the tools sit idle. With the rule, Claude treats your project journal as load-bearing memory.

Tools (17 total, grouped by use case)

Catch up on a project (use these FIRST when starting work)

| Tool | When | |---|---| | journal_list(project, last_days) | Browse the library — what journals exist | | journal_handoff_brief(name) | Fast 30-line catch-up: header + last 5 entries | | journal_read(name, max_kb) | Full journal contents | | journal_read_section(name, section) | Just the Current state / Roadmap / Handoff section | | journal_list_sections(name) | See available H2 sections |

Log work as it ships (use these DURING work)

| Tool | When | |---|---| | journal_append(name, entry, tag) | Timestamped entry after each shipped piece of work | | journal_update_section(name, section, content, mode) | Replace / append / prepend a section as state changes |

Start something new

| Tool | When | |---|---| | journal_create(name, project_dir, body) | Scaffold a new project journal with all standard sections |

Search + discover

| Tool | When | |---|---| | journal_search(query, project) | Full-text search across all journals with snippets | | journal_recent_changes(last_hours) | What journals were updated lately | | journal_stats() | Library snapshot — total count, biggest, freshest |

One-time setup / hygiene

| Tool | When | |---|---| | journal_index_refresh() | Rescan roots for new / removed journal files | | journal_config_add_root(path) | Add a folder to scan | | journal_get_claude_rule() | Get the recommended CLAUDE.md rule text | | journal_install_rule(scope, confirm) | Install the rule into ~/.claude/CLAUDE.md or per-project | | journal_backup_to_drive(name, remote, folder) | Push journals to Google Drive via rclone (optional) | | vibedna_info() | Product metadata |

Journal scaffold

Each new journal starts with these sections:

## Vision / Why this exists
## Current state
## Roadmap
## Decisions log
## Incidents
## Handoff for next session
## Recent entries

No more separate HANDOFF.md / ROADMAP.md / STATE.md / NOTES.md drifting out of sync. One file. One truth.

Storage

| Path | What | |---|---| | ~/.journal/index.sqlite | Local index DB (overridable with JOURNAL_HOME env) | | ~/.journal/config.toml | Optional config (extra roots if not using JOURNAL_ROOTS env) | | <your-project-folder>/*JOURNAL.md | Your actual journal files — stay where they live |

Nothing leaves your machine. No telemetry, no analytics, no phone-home. The one exception is journal_backup_to_drive(), which only runs when you explicitly call it and only uploads to YOUR rclone-configured Drive.

Disk layout (full picture)

<unzip-folder>/
├── server.py            ← the MCP (all 17 tools)
├── bulletproof.py       ← process hygiene helper, bundled, optional
├── requirements.txt     ← just `mcp>=1.0.0`
├── INSTALL.md           ← drop-into-Claude install handbook
├── README.md            ← this file
├── SECURITY.md          ← threat model + data boundary
└── LICENSE              ← MIT

That's it. Six files.

Privacy + Security

See SECURITY.md for the full threat model, data boundary, and how to report a vulnerability.

Short version: Journal reads + writes only *JOURNAL.md files in folders you configure. The index DB is local SQLite. Nothing is sent anywhere unless you explicitly call the optional Drive backup tool.

License

MIT. Fork it, ship it, modify it. Don't call your fork "VibeDNA Journal."

Support

Email: dev@vibedna.ai
Site: https://vibedna.ai
Issues: https://github.com/marstudio360/journal-mcp/issues

— VibeDNA, 2026

MCP Servers