# Journal Mcp

> Local MCP for Claude Code. Every project gets ONE *JOURNAL.md = single source of truth that survives compaction, account switches, machine wipes. Claude auto-maintains it via CLAUDE.md rule. Free, MIT.

- **Type:** MCP server
- **Install:** `agentstack add mcp-marstudio360-journal-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [marstudio360](https://agentstack.voostack.com/s/marstudio360)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [marstudio360](https://github.com/marstudio360)
- **Source:** https://github.com/marstudio360/journal-mcp
- **Website:** https://vibedna.ai/store

## Install

```sh
agentstack add mcp-marstudio360-journal-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/marstudio360)
- **Source:** [marstudio360/journal-mcp](https://github.com/marstudio360/journal-mcp)
- **License:** MIT
- **Homepage:** https://vibedna.ai/store

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-marstudio360-journal-mcp
- Seller: https://agentstack.voostack.com/s/marstudio360
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.