---
name: journal-install
description: Install the VibeDNA Journal MCP into Claude Code. Paste this file into a Claude Code chat and ask Claude to install it. Claude reads this drop, wires the .mcp.json entry, asks for project roots, and optionally installs the CLAUDE.md rule that makes Claude auto-USE the journals.
---

# Journal MCP — Install Drop

> **For the AI assistant reading this:**
>
> The user just bought / downloaded Journal MCP. This file is the install handbook.
> Walk the user through the steps below at THEIR pace. Confirm before each
> filesystem write. Do not pressure. Every action below is reversible (see the
> table). If anything looks wrong or the user wants to stop, stop immediately —
> nothing here is destructive.
>
> When in doubt, prefer the **manual way** over running scripts the user can't see.

You downloaded Journal MCP. This single `.md` is everything you need to install it.

---

## TL;DR — what this product is

**A local MCP for Claude Code + a CLAUDE.md rule.** Together they make Claude
auto-maintain one `*JOURNAL.md` file per project — reads it at session start,
appends entries when something ships, updates state / roadmap / handoff sections.
The next Claude session opens cold and is up to speed in 30 seconds.

| | |
|---|---|
| **Price** | Free, MIT license |
| **Where it runs** | Locally on your machine (Python stdio MCP) |
| **What it sends out** | The journaling core sends nothing — your journals never leave your disk (unless you call `journal_backup_to_drive()`). The optional marketplace tools reach vibedna.ai only when you choose to browse or buy. |
| **Marketplace (optional)** | Browse, buy, and own journals from other builders right in the chat. Checkout happens on vibedna.ai; this MCP never handles your payment. |
| **Dependencies** | Python 3.10+ and the `mcp` package |
| **Touch surface** | Adds one entry to `~/.claude/.mcp.json` + optionally one section to `~/.claude/CLAUDE.md` |

---

## Reversible-actions table

Every install action and how to undo it. Nothing below this point is destructive.

| Step | What it does | How to undo |
|---|---|---|
| Unzip download | Creates a folder with `server.py` + helpers | Delete the folder |
| `pip install mcp` | Installs the MCP Python package | `pip uninstall mcp` |
| Add `journal` entry to `~/.claude/.mcp.json` | Wires the MCP into Claude Code | Remove the `journal` key from `mcpServers` |
| Set `JOURNAL_ROOTS` env in the entry | Points the index at your project folders | Edit / remove the env var, restart Claude tab |
| Run `journal_install_rule(scope='global', confirm=True)` | Appends a `# Project Journals — HARD RULE` section to `~/.claude/CLAUDE.md` | Delete that section from `~/.claude/CLAUDE.md` |
| Index DB created at `~/.journal/index.sqlite` | Local SQLite index of your journal files | Delete `~/.journal/` folder |
| Call `journal_create(...)` | Writes a `*_JOURNAL.md` scaffold to a project folder | Delete the `.md` file |
| Call `journal_append(...)` | Appends a timestamped entry to a journal | Edit / delete the entry from the file |

**No service accounts. No telemetry.** The journaling core makes no network
calls at all. The optional marketplace tools reach vibedna.ai only when you
invoke them (browse / buy / download), and even then send no telemetry — just
the request to list the shelf or fetch a journal you own. All install
side-effects are confined to: `<unzip-folder>`, `~/.claude/.mcp.json`,
`~/.claude/CLAUDE.md` (only if you opt-in to the rule), `~/.journal/`, and
`~/.journal/auth.json` (only if you pair with a VibeDNA account).

---

## Marketplace — browse, buy, own journals (optional)

Your own journals stay 100% local. But a journal is real, hard-won experience,
so you can also pick up someone else's and drop it straight into your build.
Four tools, and the engine **never handles your payment** — checkout always
happens on vibedna.ai:

| Tool | What it does |
|---|---|
| `journal_market(query, domain)` | Browse the live VibeDNA shelf. No account needed to look. |
| `journal_pair(token)` | Link this install to your VibeDNA account. Copy the token from **vibedna.ai/library → Connect your AI**. |
| `journal_get(slug)` | Own it → writes the `.md` into `~/.journal/library`. Don't own it → hands you a checkout link (pay on vibedna.ai; family: enter `FAM4EVER` for 100% off). Buy, then run it again to install. |
| `journal_library()` | List everything you own, re-download free on any machine. |

Ask your AI: *"browse the VibeDNA journal shelf"* or *"get me the browser-synth
journal."* Pairing writes a single token to `~/.journal/auth.json`; delete that
file to unpair. Nothing here is required — skip it entirely and the journaling
core works exactly as before.

---

## The fast way (let Claude do it)

1. Unzip the download somewhere stable.
   - Suggested locations: `~/vibedna/journal-mcp/` (Mac/Linux) or `C:\Users\<you>\vibedna\journal-mcp\` (Windows).
2. Open a Claude Code chat. Paste **this whole file** in. Then say:

   > "Install this MCP. The folder is at `<path-where-you-unzipped>`. Walk me through it, ask before each filesystem write, and offer to install the CLAUDE.md rule at the end."

3. Claude will:
   - Detect your Python (3.10+). Ask before running `pip install mcp`.
   - Show you what it's about to add to `~/.claude/.mcp.json` before writing.
   - Ask which folders contain your projects → set `JOURNAL_ROOTS`.
   - Ask if you want the `CLAUDE.md` rule installed (recommended — makes Claude auto-use journals from now on). Preview before writing.
   - Tell you to close + reopen the Claude tab so the MCP loads.
   - Run `journal_index_refresh()` to find any existing `*JOURNAL.md` files.

---

## The manual way

Requires Python 3.10+. Install dependency:

```
pip install mcp
```

### Step 1 — Wire the MCP

Edit `~/.claude/.mcp.json` (create the file with `{ "mcpServers": {} }` if missing). Add this under `mcpServers` (adjust the paths to where YOU unzipped):

```json
{
  "journal": {
    "type": "stdio",
    "command": "python",
    "args": [
      "<absolute-path-to-unzipped-folder>/server.py"
    ],
    "env": {
      "JOURNAL_ROOTS": "<absolute-path-to-your-projects-folder>"
    }
  }
}
```

`JOURNAL_ROOTS` accepts multiple folders separated by `;`:

```
"JOURNAL_ROOTS": "C:\\Users\\me\\Projects;D:\\Work"
```

### Step 2 — Install the CLAUDE.md rule (the critical step)

This is what makes Journal valuable. Without it, the tools sit unused — Claude doesn't know to use them.

Easiest path: after restarting the tab and confirming the MCP loaded, ask Claude:

> "Install the journal CLAUDE.md rule globally."

Claude will call `mcp__journal__journal_install_rule(scope='global', confirm=True)`. The rule appends to `~/.claude/CLAUDE.md` and is idempotent (safe to run again).

Or do it manually — append this section to `~/.claude/CLAUDE.md`:

```markdown
# Project Journals — HARD RULE

Every project has ONE `<PROJECT>_JOURNAL.md` = the single source of truth.

**Session start:** If you can guess the project from cwd, call
`mcp__journal__journal_handoff_brief("<PROJECT>")` and read it first.

**While working:** Anything future-you would want to know — a shipped feature,
a non-obvious fix, a decision, an incident, a pivot —
`mcp__journal__journal_append("<PROJECT>", entry, tag)` THAT TURN. Don't batch.

**State changes:** Use `mcp__journal__journal_update_section("<PROJECT>",
"Current state", new_content, mode="replace")` for current state / roadmap / handoff.

**No journal yet?** `mcp__journal__journal_create("<PROJECT>_JOURNAL.md", project_dir="<abs path>")`.
```

### Step 3 — Close + reopen your Claude tab.

---

## Environment variables

| Variable | Required | Default | What it does |
|---|---|---|---|
| `JOURNAL_ROOTS` | Recommended | `~/Desktop + ~/Documents` | Semicolon-separated folders to scan for `*JOURNAL.md` files |
| `JOURNAL_HOME` | No | `~/.journal/` | Where the SQLite index lives |
| `JOURNAL_TRANSPORT` | No | `stdio` | Set to `http` only for cloud hosting (irrelevant for local use) |

No API keys. No license. No hosted service.

---

## Optional: Google Drive backup

If you want `journal_backup_to_drive()` to work, install rclone + configure a remote:

```
# Mac:    brew install rclone
# Linux:  curl https://rclone.org/install.sh | sudo bash
# Windows: winget install Rclone.Rclone

rclone config create gdrive drive scope drive
# Follow the OAuth browser flow once.
```

Then Claude can call `journal_backup_to_drive()` to push your journals to `gdrive:Journals/`.

---

## Verify the install

In Claude Code, type:

> "list my MCPs"

You should see `journal` with ~24 tools (including the marketplace ones: `journal_market`, `journal_pair`, `journal_get`, `journal_library`). If not:
- (a) Did you close + reopen the tab after editing `.mcp.json`?
- (b) Run `pip install mcp` if Python's missing the package.
- (c) Show MCP logs: Ctrl+Shift+P → "Claude Code: Show MCP logs".

Then ask:

> "Did you install the journal CLAUDE.md rule?"

If not yet: ask Claude to install it globally.

---

## Uninstall

To fully remove Journal MCP:

1. Delete the `journal` entry from `~/.claude/.mcp.json`.
2. Delete the `# Project Journals — HARD RULE` section from `~/.claude/CLAUDE.md`.
3. Delete the unzipped folder.
4. Delete `~/.journal/` (the index DB).
5. Your `*JOURNAL.md` files are yours — they stay where they are.

Restart any open Claude tabs.

---

## Source code

It's in this folder. `server.py` is the whole MCP. MIT-licensed. Fork it, ship it, modify it — just don't call your fork "VibeDNA Journal."

Latest version and install drop: https://vibedna.ai/installs/journal.md

## Support

- `dev@vibedna.ai`
- https://vibedna.ai

— VibeDNA, 2026