VibeDNA Journal

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

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

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:

{
  "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

MIT, see LICENSE. Copyright (c) 2026 VibeDNA.

Support: [email protected]