Open source Local first Agent ready

joplin-md-sync

Give agents useful access to your notes without giving up control of them. Bridge self-hosted Joplin to reviewable Markdown, MCP clients, and ChatGPT Actions through one safety-focused tool.

Start in five minutes View on GitHub

MIT licensed Windows and Linux Zero runtime dependencies

safe agent session verified
JoplinYour private source
local Data API
J
joplin-md-syncGuard, apply, verify
Markdown / MCP
>_
Your agentStructured, bounded access
$ joplin-md-sync push --root ./notes --dry-run --json {"code":"PENDING_ACTIONS","exit_code":1,"planned_operations":1}
Pulled first Three-way diff No silent overwrite Recovery journal

One knowledge base, two ways to work

Your notes stay yours. Agents become useful.

Joplin remains the place where you capture, organize, encrypt, and sync knowledge. The bridge adds controlled interfaces for the work agents do best.

01

Review every edit

Pull notes into ordinary Markdown, let an agent make a focused change, inspect a true three-way diff, then dry-run the exact push plan.

Use the file workflow →
02

Call Joplin directly

Search, read, create, tag, move, and trash notes through typed MCP tools when an immediate structured operation is the better fit.

Explore the MCP API →
03

Host the whole path

Run Joplin Terminal and the authenticated bridge on your own Linux host, while keeping the upstream Data API private on loopback.

Plan a self-hosted setup →

Built for real note workflows

Six jobs, one controlled bridge

Use the interface that matches the task. Reviewed file transformations and immediate API operations are intentionally separate.

Developers

Agent-maintained runbooks

Let a coding agent update commands, rollback steps, and incident notes from the project it is already working in.

Second brain

Private semantic work

Find related notes, summarize a topic, and organize results without exporting your whole notebook archive to another note platform.

Git

Versioned knowledge

Keep a reviewable history of selected Joplin notebooks as Markdown while local state, credentials, backups, and conflicts stay out of Git.

MCP

Tools for any compatible client

Expose notes, notebooks, tags, search, and attachments over Streamable HTTP with explicit schemas and bounded payloads.

ChatGPT

Your own Joplin assistant

Connect a private Custom GPT through authenticated Actions, generated OpenAPI, isolated credentials, and a tested HTTPS endpoint.

Homelab

Headless knowledge service

Pair Joplin Terminal with systemd services and your chosen sync target, without exposing Joplin's own Data API to the internet.

Control is the feature

Self-hosted notes should not require blind trust.

Your notes can stay in Joplin, on infrastructure and sync targets you choose. joplin-md-sync works through the documented Data API, never the Joplin database or profile internals.

Read the security model →
Interface Markdown workspace or MCP / Actions Choose reviewed changes or direct tools per task
Safety Plan → guard → apply → verify Stable exit codes and deterministic JSON at every boundary
Joplin Loopback Data API Tokens remain separate; remote access requires an explicit override
Owner Your profile, storage, sync, and backups No replacement cloud and no proprietary note format

A boringly explicit write path

See what will change before Joplin changes.

The file workflow gives autonomous agents the same guardrails a careful operator would use by hand.

  1. 1
    PullStart from current Joplin state.
  2. 2
    EditWork in plain Markdown with normal tools.
  3. 3
    DiffCompare base, local, and remote states.
  4. 4
    Dry-runReview the exact operation plan.
  5. 5
    PushGuard, apply, verify, and journal.
notes-agent-session.sh exit codes are part of the API 
$ joplin-md-sync pull --root ./notes --json
OK  remote and base refreshed

$ joplin-md-sync diff --root ./notes \
    --three-way --unified
1 note  body changed locally

$ joplin-md-sync push --root ./notes \
    --dry-run --json
PENDING_ACTIONS  push_update_remote

$ joplin-md-sync push --root ./notes --json
OK  applied 1, failed 0

Failure is a first-class state

Designed to stop, explain, and recover.

Automation is only useful when its boundaries are predictable. The CLI never hides a divergent edit behind a successful-looking message.

No silent overwritesDivergent edits produce a conflict bundle and exit code 2.
No default deletionDeletes are reported until an explicit propagation flag is approved.
No mystery partial runsA journal blocks further writes until recovery verifies what completed.
No token in argumentsCredentials come from protected files or the environment and are redacted.
No direct database accessOnly Joplin's documented local Data API is used.
No mutating diffdiff is guaranteed to inspect state without changing it.

Keep Joplin. Add a safer interface.

Make your private notes useful to agents.

Install and connect Choose an interface
joplin-md-sync is an independent open-source project and is not affiliated with or endorsed by the Joplin project.