Joplin Server MCP
Allows interaction with Joplin Server, providing tools for managing notebooks, notes, tags, and attachments via the Joplin Server REST API.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Joplin Server MCP
Model Context Protocol server for Joplin Server. Gives LLMs full access to your notes, notebooks, tags, and attachments via the Joplin Server REST API.
What is Joplin Server?
Joplin is an open-source note-taking app with Markdown support, end-to-end encryption, and sync across devices. Joplin Server is the sync backend that stores and syncs your data. You can run it yourself using the official Docker image or use the managed Joplin Cloud service.
Note: This MCP server connects to Joplin Server REST API, not the Joplin Desktop Web Clipper.
Joplin Cloud: Use
JOPLIN_SERVER_URL=https://api.joplincloud.com.
Related MCP server: joplin-mcp
Tools
Tool | Description |
| Check server connectivity |
| List all notebooks |
| Get notebook details with notes and sub-notebooks |
| Create a new notebook |
| Resolve a |
| Rename or move a notebook (with circular reference check) |
| Delete a notebook (with optional force for non-empty) |
| List notes, optionally filtered by notebook, tag, and/or to-do state |
| Get all notes with pagination, sorting (incl. |
| Search notes (multi-term AND) with scope and notebook/tag filters |
| Get note text (resource references replaced with names, or |
| Read multiple notes at once (up to 50, parallel) |
| Get note with all resources embedded as base64 |
| Create a new note (optionally as a to-do with a due date) |
| Export note as markdown with resources as named base64 blocks |
| Update note title, body, or move to another notebook |
| Map a note's headings with line numbers and section sizes |
| Add text inside a note or section, or as a sibling before/after a section |
| Replace an exact string inside a note body |
| Replace everything under a heading |
| Set/clear a note's to-do state, completion, and due date |
| Delete a note |
| List all tags |
| Create a new tag |
| Delete a tag |
| List tags assigned to a note |
| Add a tag to a note |
| Remove a tag from a note |
| List resources attached to a note |
| Get resource metadata |
| Download a resource as base64 |
Partial edits
update_note takes the complete new body, which makes it a poor fit for large
notes: adding two lines to a 70 KB note means an LLM has to reproduce all 70 KB
verbatim. That is expensive, and a single silent typo corrupts the note.
append_to_note, replace_in_note and replace_section resolve the edit on
the server instead. The client sends only the fragment it wants added or
changed, so untouched text — including :/<resource-id> links, which the read
tools render as human-readable names — is preserved byte for byte.
append_to_note(note_id, "| web-1 | 10.0.0.5 |", section="Hosts", separator="\n")
append_to_note(note_id, "## 2026-08-26\n\nDeployed.", section="## 2026-08-25", position="before")
replace_in_note(note_id, "status: draft", "status: final")
replace_section(note_id, "## Current state", "Rewritten from scratch.")Every write reports what it did — character and line deltas, heading count before and after, and the numbered lines around the change — so the result can be verified without re-reading the note:
Appended to: **Work Log** (ID: `0123456789abcdef0123456789abcdef`)
Inserted 745 chars at the start of section '# Work Log' (line 1)
Chars 76141 -> 76887 (+746), lines 1858 -> 1885 (+27), headings 117 -> 118Guard rails:
Sections are addressed by heading, either bare (
"Hosts") or with its level ("## Hosts"), and a section ends at the next heading of the same or higher level. Headings inside fenced code blocks are ignored. An ambiguous or missing heading is refused, never guessed.get_note_outlinelists what is available without reading the body.positionpicks inside or beside."start"/"end"write inside the note or section, joining the existing content withseparator."before"/"after"place the text beside a named section instead — above its heading, or past its whole span with subsections included. Those two requiresection, ignoreseparator, and are strictly additive: no existing byte is rewritten and blank lines appear only where the join needs them. Reach for"before"to put a new entry at the top of a newest-first log whose first heading is preceded by a preamble —"start"would land above the preamble.replace_in_notedemands a unique match. A missing anchor or an unexpected second match is an error, with the mismatching lines reported. Useget_note(raw=True)to copy an anchor verbatim, orreplace_all=Truewhen you do mean every occurrence.dry_run=Truereports the change and its context without writing.if_absent="marker"skips the append when the marker is already in the note, which makes a re-run a no-op.
Setup
Prerequisites
A running Joplin Server instance or Joplin Cloud account
User credentials (email + password)
Environment variables
Variable | Required | Default | Description |
| Yes | — | Joplin Server URL |
| Yes (single-user) | — | User email |
| Yes (single-user) | — | User password |
| No |
| Transport: |
| No |
| HTTP listen host ( |
| No |
| HTTP listen port ( |
| No |
|
|
| No |
| Multi-user: name of the header carrying |
| No |
| Multi-user: evict an account (index, session, password) after this much idle time |
| No |
|
|
| No |
| Multi-user: directory of the per-account cache files |
streamable-http serves the endpoint /mcp and is the transport the current
MCP specification recommends; sse (endpoint /sse) is the older one, kept as
the image default for compatibility.
Run with Docker
docker run -d \
-e JOPLIN_SERVER_URL=https://your-joplin-server.example.com \
-e JOPLIN_EMAIL=your@email.com \
-e JOPLIN_PASSWORD=your_password \
-p 8081:8081 \
alexfail2/joplin-mcpThe container defaults to SSE transport. The endpoint will be available at http://localhost:8081/sse.
Add -e MCP_TRANSPORT=streamable-http to serve http://localhost:8081/mcp instead.
Run locally (stdio)
pip install -r requirements.txt # mcp, httpx, uvicorn, pinned
python app/server.pyBuild from source
docker build -t joplin-mcp .MCP client configuration
Streamable HTTP
{
"mcpServers": {
"joplin": {
"url": "http://localhost:8081/mcp"
}
}
}SSE (Docker default)
{
"mcpServers": {
"joplin": {
"url": "http://localhost:8081/sse"
}
}
}stdio (local)
{
"mcpServers": {
"joplin": {
"command": "python",
"args": ["/path/to/app/server.py"],
"env": {
"JOPLIN_SERVER_URL": "https://your-joplin-server.example.com",
"JOPLIN_EMAIL": "your@email.com",
"JOPLIN_PASSWORD": "your_password"
}
}
}
}Multi-user mode
By default one server instance serves one Joplin account (the one in
JOPLIN_EMAIL / JOPLIN_PASSWORD). With JOPLIN_MULTI_USER=1 a single
instance serves many users: each request carries that user's own Joplin
credentials in a header, and every tool call runs against that user's account.
How it works
The client sends
X-Joplin-Credentials: email:passwordwith every request (the value is split at the first colon, so passwords may contain colons). The header name is configurable withJOPLIN_CREDENTIALS_HEADER.An ASGI middleware reads the header, logs in to Joplin Server (or reuses the session it already has for that account) and binds the account to the request. Without the header, or with credentials Joplin rejects, the request is answered with HTTP 401 before reaching any tool, so clients report "unauthorized" instead of a tool error. More than 5 failed logins for one account within 5 minutes are answered with 429.
Each account has its own state: session, index, resource index and background refresh tasks. Accounts are keyed by
sha256(server URL + lowercased email); an account idle forJOPLIN_ACCOUNT_IDLE_MINUTES(default 30) is evicted and its background tasks cancelled.JOPLIN_SERVER_URLis only read from the environment, never from a header.JOPLIN_EMAIL/JOPLIN_PASSWORDare not required and are never used in this mode.The index cache on disk is one file per account in
JOPLIN_CACHE_DIR, named by the account hash, mode0600in a0700directory, and loaded only after a successful login.JOPLIN_DISK_CACHE=0turns it off. The files contain note titles and bodies in clear, so put the directory on storage you trust.Credentials are never logged or put in error messages.
Multi-user mode needs an HTTP transport.
streamable-httpis recommended: it runs stateless, so each request is executed with the credentials of that request. Withssethe account is fixed when the SSE connection is opened.Single-user mode is unchanged: no header is needed, stdio works, and if a credentials header is sent anyway it is ignored (a warning is logged once).
Docker example
docker run -d \
-e JOPLIN_SERVER_URL=https://your-joplin-server.example.com \
-e JOPLIN_MULTI_USER=1 \
-e MCP_TRANSPORT=streamable-http \
-v joplin-mcp-cache:/tmp/joplin-cache \
-p 127.0.0.1:8081:8081 \
alexfail2/joplin-mcpClient configuration
Any MCP client that can send a per-user header works, for example a chat application whose connector lets each user provide their own key and choose the header name:
{
"mcpServers": {
"joplin": {
"url": "https://joplin-mcp.internal.example.com/mcp",
"headers": { "X-Joplin-Credentials": "you@example.com:your_joplin_password" }
}
}
}Limitations
Joplin Server has no personal access tokens. Each user's Joplin password is therefore sent with every request, and the client has to store it (encrypted in the client, if it supports that).
The MCP server holds the password of every active user in memory and logs in to Joplin on their behalf. A compromise of the server exposes the accounts of all active users. Run it only on a private network or behind TLS, never on the public internet without TLS.
One Joplin Server per instance (
JOPLIN_SERVER_URL).The index is kept per user in memory, so memory grows with the number of active users; idle accounts are evicted after
JOPLIN_ACCOUNT_IDLE_MINUTES.There is no revocation separate from Joplin itself: changing the Joplin password is the only way to cut access (an already-open session keeps working until Joplin rejects it).
How it works
The server authenticates with Joplin Server via email/password sessions and builds an in-memory index of all items (notes, notebooks, tags) with a 2-minute TTL cache. Incremental sync compares server-side updated_time with cached etags, fetching only changed items (typical refresh: ~5s vs ~35s full rebuild). The index is persisted to /tmp/joplin_index_cache.json (one file per account in multi-user mode, see above; JOPLIN_DISK_CACHE=0 disables it) so a restarted container starts instantly; a recreated one rebuilds it on first use. Resource metadata is loaded lazily on first access. Background refresh keeps the index up to date without blocking requests. All IDs are validated (32-char hex) before API calls.
Joplin's internal serialization format (title + markdown body + metadata block) is parsed and presented as clean structured output.
Development
The pure helpers (markdown section resolution, splicing, edit reports, to-do state) are covered by a dependency-free test suite:
python tests/test_helpers.pyThe multi-user tests use pytest and a fake Joplin API (tests/fake_joplin.py):
pip install -r requirements-dev.txt
python -m pytest tests
python tests/smoke_multi_user.py 8381 # end-to-end, streamable-http, two usersContributors
@paoloviviani — to-do state: completion and due dates surfaced and settable,
set_todo,create_noteflags,todofilters and ordering (#7)@LasseLegarth —
share_idinherited from the parent notebook, so notes stay visible to a shared notebook's participants (#5)
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceMCP server that provides standardized tools for querying and retrieving notes from Joplin personal knowledge manager through its API, enabling AI assistants to access and reference personal notes contextually.9-
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Joplin note-taking app, enabling AI to read, search, and modify notes via sandboxed scripts.222 npm27Apache 2.0
- AlicenseAqualityBmaintenanceA minimal MCP server that enables interaction with Joplin notes and notebooks through the local Web Clipper REST API, providing tools for search, create, update, and note management.13MIT
- AlicenseNot gradedqualityBmaintenanceA Model Context Protocol server that wraps Joplin's Data API, giving agents full CRUD over notes, notebooks, tags, and resources, plus search and revision history.MIT