Joplin MCP for Claude & ChatGPT

Joplin MCP server for Claude, ChatGPT and AI agents

Claude & ChatGPT Local & HTTP MCP Self-hosted Joplin

Joplin MCP for Claude & ChatGPT

Search, read, create, organize, and update your own Joplin notes from the assistants you already use. Connect Claude with a GitHub login, give a private ChatGPT GPT live access, launch a local MCP process over stdio with no listener, or deploy guarded HTTP interfaces while keeping Joplin, its sync target, and its Data API under your control.

Connect Claude Connect ChatGPT Connect local MCP Deploy headless

Built-in OAuth for hosted Claude Claude on claude.ai connects straight to Joplin on your own server through your GitHub login. OAuth is part of the server, so there is no separate OAuth proxy or gateway to deploy and configure.
ChatGPT today A private Custom GPT works through authenticated Actions. OpenAI retires Custom GPTs on 2026-12-11; a ChatGPT MCP connector through the same built-in OAuth is planned as the replacement.
One installer for the whole stack A single command sets up headless Joplin, sync, MCP, Actions, and Claude OAuth. It asks for the values it needs, hides secrets, generates keys and tokens, and verifies the result.

Open source Private by design Desktop optional

private Joplin assistant authenticated

Claude, ChatGPT or MCPYour chosen client

typed operations

Guarded bridgeAuthenticate, validate, execute

loopback Data API

Your JoplinYour profile and sync target

You Find my notes about the production migration. Tool joplin_search_notes {"query":"production migration"} {"success":true,"results":[{"title":"Migration runbook"}]}

Claude connector ChatGPT Actions MCP tool schemas Private Joplin API

One knowledge base, direct agent access

Use Joplin where you already think and work.

Joplin remains the system of record. The bridge adds authenticated, structured interfaces without introducing another note store or requiring a permanent desktop session.

Talk to your notes in Claude or ChatGPT

Connect hosted Claude through your own GitHub login, or give a private Custom GPT live access to search, read, create, update, move, tag, and trash exact Joplin objects.

Connect Claude to Joplin →

Connect any MCP client

Launch typed local stdio tools with no listener, or expose Streamable HTTP for notes, notebooks, tags, search, and attachments.

Explore the MCP tools →

Run Joplin without a desktop

One interactive installer sets up Joplin Terminal, recurrent sync, MCP, Actions, and Claude OAuth as coordinated rootless services on a Linux host.

Deploy Joplin Headless Service →

Joplin's built-in MCP server or this bridge

Reach your notes beyond the desktop.

Joplin Desktop can expose its own MCP server on the Web Clipper port to clients on the same computer. Use this bridge when the assistant runs elsewhere, Joplin runs without a desktop, or a change needs review. Its OAuth is built in, so reaching hosted Claude takes no extra proxy.

	Joplin's built-in MCP	joplin-md-sync
Hosted assistants	Not reachable: clients must run on the same computer	Hosted Claude through built-in GitHub OAuth with no separate OAuth proxy, and ChatGPT through a private Custom GPT with Actions
Where it runs	Inside Joplin Desktop, which must stay open with the Web Clipper service	Beside Joplin Desktop, or headless on a Linux server with Joplin Terminal and recurrent sync
Other MCP clients	Local clients through 127.0.0.1	Local stdio with no listener, or authenticated Streamable HTTP over HTTPS
Setup	Switches in the desktop settings	One installer configures Joplin Terminal, sync, tokens, and OAuth from your answers
Authentication	The Web Clipper token in the request URL	Separate MCP and Actions bearer tokens, plus GitHub OAuth limited to one account
Attachments	Not exposed as tools	Read, upload, replace, and delete resources and their note links
Bulk changes	Individual tool calls	Two-way Markdown sync with three-way diffs and dry-run pushes
Search	Keyword and semantic search over the local embeddings index	Joplin keyword search; the tool guides assistants to retry with synonyms and word stems

Only local desktop clients, and semantic search matters most? The built-in server is enough. Choose an interface →

From sync target to your assistant

Deploy the complete headless path.

One installer coordinates Joplin Terminal and the agent adapter. It asks for the sync target, tokens, and the GitHub OAuth settings for Claude, hides secrets, and checks the running services. You bring an HTTPS hostname; the upstream Data API never needs to leave loopback.

Review the deployment boundaries →

1
Choose storageConnect the headless profile to your existing Joplin sync target.
2
Install servicesDeploy Joplin Terminal and the shared MCP, OAuth, and Actions adapter.
3
Publish safelyRoute only the authenticated MCP, OAuth, or Actions paths through HTTPS.
4
Connect your assistantAdd the connector in Claude, or generate the Action schema for a private GPT.
5
Use your notesSearch and change current Joplin data from Claude, ChatGPT, or MCP.

headless-joplin.sh rootless systemd services

$ set -o pipefail
$ curl --proto '=https' --tlsv1.2 --fail \
    --silent --show-error --location \
    https://raw.githubusercontent.com/kogeler/\
joplin-md-sync/main/scripts/joplin_terminal_service/\
install_joplin_terminal.py | python3 - \
    --sync-target nextcloud \
    --sync-location https://cloud.example/Joplin \
    --sync-username user

OK  joplin-terminal.service active
OK  joplin-md-sync.service active
OK  separate MCP and Actions tokens created
OK  GitHub OAuth for Claude enabled and verified

Useful every day

Current notes, not another stale export.

Both direct interfaces use the same validated operation registry. Choose Claude or ChatGPT for conversation, or MCP for any compatible client.

Claude & ChatGPT

Search and synthesize your knowledge

Find the relevant Joplin notes, read only the selected results, and turn current private context into a focused answer.

Capture

Turn a conversation into a note

Create a decision record, meeting follow-up, research summary, or checklist in the exact notebook you name.

Organize

Maintain notebooks and tags

Rename, move, tag, restore, and trash exact objects while duplicate identities are rejected instead of silently multiplied.

MCP

Bring Joplin into an agent workspace

Let an MCP-capable editor or coding assistant inspect runbooks and update targeted notes without exporting the whole archive.

Resources

Work with attachments through MCP

Read, upload, replace, and traverse note-resource relationships with bounded payloads and explicit destructive operations.

Always on

Keep the assistant available headlessly

Run recurrent Joplin sync and the adapter as user services on your server while desktop and laptop clients come and go.

Control is the feature

Your assistant should adapt to your notes, not own them.

Keep the Joplin clients, sync provider, encryption choices, profile, and backups you already trust. The bridge is a replaceable open-source adapter, not a new proprietary knowledge store.

Read the security contract →

Clients Claude, a private GPT or an MCP client Separate transports over one shared, validated operation registry

Boundary Dedicated MCP, Actions, and OAuth credentials Independent tokens, authenticated routes, and bounded payloads

Joplin Loopback Data API The upstream token and API never need public network exposure

Owner Your Joplin profile, sync target, encryption, and backups Remove the adapter without migrating or deleting your knowledge base

A second interface for review-heavy work

Use ordinary Markdown when the diff matters.

Direct tools are ideal for current, targeted operations. For broad changes, repository context, or Git review, pull selected Joplin notebooks to files and approve the exact push plan.

1
PullStart from current Joplin state.
2
EditWork in plain Markdown with normal agent tools.
3
DiffCompare base, local, and remote states.
4
Dry-runReview the exact operation plan.
5
PushGuard, apply, verify, and journal.

reviewed-note-change.sh stable JSON and exit codes

$ 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

Predictable failure boundaries

Agents get explicit errors, not accidental damage.

Direct tools and file synchronization use different consistency models, but both expose failures instead of guessing or silently repeating writes.

No duplicate create retriesOccupied note, notebook, tag, and resource identities return the existing IDs and recommended update tool.

No ambiguous write replayA timed-out direct mutation is reported for inspection instead of being sent again.

No public Joplin APIRemote clients reach the authenticated adapter; Joplin stays on loopback.

No permanent note deletionNotes and notebooks move to normal Joplin trash and can be restored.

No silent file overwriteDivergent edits produce a three-way conflict bundle and exit code 2.

No hidden partial syncA journal blocks later file writes until recovery verifies what completed.

Keep Joplin. Add the interfaces you need.

Bring your private notes into Claude, ChatGPT, and MCP.

Connect Claude Compare interfaces

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