VibeDNA Journal MCP

One journal file per project that your AI reads at session start and updates as it works.

Journal gives every project one plain markdown file (*_JOURNAL.md). Your AI reads it when a session starts and appends to it as work ships: decisions with their reasons, bugs with root cause and fix, current state, roadmap, and a handoff note for the next session. Ranked full-text search finds an entry across every project's journal at once. One optional tool adds a rule to your CLAUDE.md so Claude Code keeps the habit without being asked.

Runs locally over stdio. Python 3.10+ and the mcp package.
The journaling core makes no network calls. Your journals stay on your disk.
Optional marketplace tools browse and download journals from vibedna.ai, only when you call them.

Homepage: https://vibedna.ai/store/journal

Tools (25)

Catch up on a project

Tool	What it does
`journal_handoff_brief(name)`	Short catch-up: header plus the latest entries
`journal_read(name, max_kb)`	Full journal contents
`journal_read_section(name, section)`	One section, e.g. `Current state` or `Handoff for next session`
`journal_list_sections(name)`	The H2 sections of a journal
`journal_list(project, last_days)`	List the journals in the index

Log work as it ships

Tool	What it does
`journal_append(name, entry, tag)`	Timestamped entry
`journal_update_section(name, section, new_content, mode)`	Replace, append or prepend a section
`journal_create(name, project_dir, body)`	New journal with the standard sections

Search

Tool	What it does
`journal_search(query, project)`	Ranked full-text search (SQLite FTS5) across all journals, with snippets
`journal_recent_changes(last_hours)`	Journals updated lately
`journal_stats()`	Totals, biggest and freshest journals
`journal_browse(domain, tier, kind, tag)`	Browse the local library by metadata
`journal_market_index(kind)`	Local feed of journals of one kind, with metadata
`journal_overlap_check(name)`	Find journals that overlap with this one

Setup

Tool	What it does
`journal_index_refresh()`	Rescan the roots for journal files
`journal_config_add_root(path)`	Add a folder to scan
`journal_get_claude_rule()`	The recommended `CLAUDE.md` rule text
`journal_install_rule(scope, confirm)`	Install that rule (preview unless `confirm=True`)
`journal_backup_to_drive(name, remote, remote_folder)`	Copy journals to your own rclone remote (optional)
`check_for_update()`	Compare this copy with the published version
`vibedna_info()`	Product metadata

Marketplace (optional, reaches vibedna.ai)

Tool	What it does
`journal_market(query, domain)`	Browse the VibeDNA journal shelf
`journal_pair(token)`	Link this install to a vibedna.ai account
`journal_get(slug)`	Download a journal you own, or get a checkout link for one you don't
`journal_library()`	List the journals you own

Install

bash

git clone https://github.com/marstudio360/vibedna-journal-mcp
cd vibedna-journal-mcp
pip install -r requirements.txt

JOURNAL_ROOTS is the list of folders to scan for journal files, separated by ;. Without it, Journal scans ~/Desktop and ~/Documents.

Claude Code

bash

claude mcp add journal --scope user -e JOURNAL_ROOTS="/path/to/your/projects" -- python /absolute/path/to/vibedna-journal-mcp/server.py

Or in a project's .mcp.json:

json

{
  "mcpServers": {
    "journal": {
      "command": "python",
      "args": ["/absolute/path/to/vibedna-journal-mcp/server.py"],
      "env": { "JOURNAL_ROOTS": "/path/to/your/projects" }
    }
  }
}

Then ask Claude: "Install the journal CLAUDE.md rule globally." That is the step that makes it read and write the journals on its own.

Cursor

Add the same mcpServers block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

Claude Desktop

Add the same mcpServers block to claude_desktop_config.json (Settings > Developer > Edit Config), then restart Claude Desktop.

INSTALL.md is a step-by-step guide written so you can paste it into an AI chat and let the AI do the install.

Configuration

Variable	Default	What it does
`JOURNAL_ROOTS`	`~/Desktop;~/Documents`	Folders to scan for `JOURNAL.md` files
`JOURNAL_HOME`	`~/.journal`	Where the search index and optional config live
`JOURNAL_TRANSPORT`	`stdio`	`http` serves streamable HTTP on `PORT`, for cloud hosting only

Journal scaffold

journal_create starts every journal with these sections:

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

Security

See SECURITY.md for what the server reads, writes and sends.

License

Support: admin@vibedna.ai

VibeDNA Journal

What it does

What it costs