Journal Mcp

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](./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) | | /*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)

/
├── 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](./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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: marstudio360
• Source: marstudio360/journal-mcp
• License: MIT
• Homepage: https://vibedna.ai/store

Install and usage instructions live in the source repository linked above.