joplin-mcp
joplin-mcp is a minimal MCP server that lets an MCP client read, write, and organize notes in a running Joplin Desktop instance via its local Web Clipper REST API, with per-notebook access control.
Search & read:
search_notes(query, limit=20)for full-text search;get_note(note_id)for a note's full content;list_notes_in_notebook(notebook_id, limit=20)to browse without a query;get_notes_by_tag(tag_id, limit=20)to list notes by tag.Write notes:
create_note(title, body, notebook_id),update_note(note_id, title, body)(only provided fields change;bodyreplaces the whole note), anddelete_note(note_id)(moves to Joplin's trash).To-dos:
complete_todo(note_id, completed=True)marks a to-do complete/incomplete (fails on non-to-do notes).Organize:
list_notebooks()andlist_tags()to discover ids;create_notebook(title, parent_id=None)at the root or nested inside an existing notebook.Access control: all note-touching tools and
create_notebookare scoped by thenotebookslist inconfig.json(readimplies default,writeimplies read;*for all;$rootfor root-level notebook creation). Fail-closed, with out-of-scope calls raisingNotebookAccessError.list_notebooks/list_tagsare unscoped metadata.Requirements/limits: Joplin Desktop must be running with the Web Clipper service enabled (no headless mode); API failures surface as
JoplinError.Note: the README also documents
update_note_sectionandappend_note_section, which are not present in this schema.
Provides tools to search, get, create, and update notes, as well as list notebooks in Joplin via its local Web Clipper REST API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@joplin-mcp list my notebooks"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
joplin-mcp
A minimal MCP server for Joplin, built with FastMCP. Talks to Joplin's local Web Clipper REST API.
Contents
Related MCP server: Joplin MCP Server
Tools
Tool | Description |
| Full-text search |
| Fetch a note's full content |
| Create a new note |
| Edit an existing note ( |
| Replace one exact, unique substring within a note's body |
| Append content to the end of a note's body |
| Delete a note (moves it to Joplin's trash) |
| Mark a to-do note complete or incomplete |
| Browse a notebook's notes without a search query |
| List notebooks, to get a |
| Create a notebook, at the root or nested inside another |
| List tags, to get a |
| List notes with a given tag |
Setup
In Joplin Desktop: Tools > Options > Web Clipper, enable the service, copy the auth token shown there.
Install uv if you don't have it.
Copy
config.example.jsontoconfig.jsonat the repo root (already gitignored, so it won't be committed) and fill in:{ "token": "paste-your-token-here", "host": "localhost", "port": "41184", "notebooks": [ {"id": "notebook-id-or-name", "access": "write"}, {"id": "another-notebook-id-or-name", "access": "read"} ] }host/portare optional and default tolocalhost/41184. See Access control below for thenotebookslist.
Running it
No manual pip install needed — uv run resolves and caches dependencies
on first run.
uv run --directory /path/to/joplin-mcp joplin-mcp-serverThis looks for config.json in the working directory (which --directory
sets to the repo). To keep the config file somewhere else, set
JOPLIN_CONFIG to its path:
JOPLIN_CONFIG=/path/to/config.json uv run --directory /path/to/joplin-mcp joplin-mcp-serverWiring into an MCP client
Both approaches below point at the repo directory, which is where
config.json lives — one source of truth for secrets and access config.
Claude Code
claude mcp add joplin -s user -- uv run --directory /path/to/joplin-mcp joplin-mcp-server-s user registers it at user scope, so it's available in every Claude
Code session, not just this repo. Verify with claude mcp get joplin;
remove with claude mcp remove joplin -s user.
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), adding:
{
"mcpServers": {
"joplin": {
"command": "uv",
"args": ["run", "--directory", "/path/to/joplin-mcp", "joplin-mcp-server"]
}
}
}Fully quit and restart Claude Desktop afterward — it only picks up config
changes on launch. This is the schema documented at
support.claude.com
and modelcontextprotocol.io.
Some Claude Desktop builds manage MCP servers through a Settings UI
(Extensions/Connectors) instead of this file directly — check there first
if the file on disk doesn't have an mcpServers key already.
Using uvx instead (no local checkout needed)
uv run --directory ... (above) operates on a project already cloned to
disk — it needs a working copy of this repo, its pyproject.toml, and its
lockfile at that path. uvx (short for uv tool run) is different: it
fetches the package straight from git into uv's own cache and runs it in
an ephemeral environment, so the machine running the MCP client doesn't
need a local clone at all — just a config.json and JOPLIN_CONFIG
pointing at it.
uvx --from git+https://github.com/johnsarie27/joplin-mcp@<ref> joplin-mcp-server<ref> can be a branch (e.g. main) or a commit SHA. A branch ref is
re-resolved to whatever the current tip commit is on every launch (a
network round-trip, and a fresh dependency resolve/build whenever that tip
changes) — convenient while iterating, but it means the running server can
change without you touching either client config. Pinning <ref> to a
specific commit SHA, per the SHA-pinning convention, freezes both the code
and its resolved dependency versions until you deliberately bump the pin —
prefer this once the repo's been stable through some real usage.
Since there's no local checkout in this mode, set JOPLIN_CONFIG to an
absolute path so config.json can still be found. Swap the command/args
in whichever client config above to uvx/--from git+... instead of
uv/run --directory ..., and add the JOPLIN_CONFIG env var:
claude mcp add joplin -s user -e JOPLIN_CONFIG=/path/to/config.json -- uvx --from git+https://github.com/johnsarie27/joplin-mcp@<ref> joplin-mcp-server{
"mcpServers": {
"joplin": {
"command": "uvx",
"args": ["--from", "git+https://github.com/johnsarie27/joplin-mcp@<ref>", "joplin-mcp-server"],
"env": {
"JOPLIN_CONFIG": "/path/to/config.json"
}
}
}
}Release tags (v<major>.<minor>.<patch>) are also valid refs — see
Releasing in CONTRIBUTING.md for how they're cut. Use
one as <ref> when pinning uvx --from git+...@<ref> above.
Tip: you can run the server standalone and call each tool manually before wiring it into a client — see Testing changes in CONTRIBUTING.md.
Access control
search_notes, get_note, create_note, update_note,
update_note_section, append_note_section, delete_note,
complete_todo, list_notes_in_notebook, get_notes_by_tag, and
create_notebook are scoped by the notebooks list in config.json. Each
entry is:
{"id": "notebook-id-or-name", "access": "read"}access is "read" (default if omitted) or "write" (implies read).
search_notes/get_note/list_notes_in_notebook/get_notes_by_tag
require read; create_note/update_note/update_note_section/
append_note_section/delete_note/complete_todo require write on the
relevant notebook. create_notebook follows the same
rule when nesting inside an existing notebook (parent_id set) — it
requires write on that parent, same as create_note. Creating a notebook
at the root (parent_id omitted) is different: it isn't scoped to any
existing notebook id, so it's governed by the $root sentinel instead —
see below. This is fail-closed: if notebooks is missing, empty, or none
of its entries grant applicable access, these tools refuse to operate.
list_notebooks and list_tags are unaffected since they only return
notebook/tag metadata, not note content, and double as the way to find the
ids/names to pass to the scoped tools above.
Name matching is case-insensitive (Tech, tech, and TECH are
equivalent) and resolved against the live notebook list on each call, so
a rename takes effect immediately. Since Joplin doesn't require notebook
names to be unique (nested notebooks can share a title), a name that
matches more than one notebook grants that access level to all of them —
use the notebook id instead (from list_notebooks) if you need to scope
to just one of several same-named notebooks.
Use {"id": "*", "access": "read"} or {"id": "*", "access": "write"} to
grant that access level to all notebooks. This is a deliberate opt-in,
distinct from leaving notebooks empty.
Use the reserved id "$root" to grant permission to create notebooks at the
root of the notebook tree — i.e. create_notebook calls that omit
parent_id:
{"id": "$root", "access": "write"}This is a separate, narrower opt-in than blanket write access: it lets a
config that only grants write on specific notebooks (e.g. Tech) also
create new top-level notebooks, without granting write access to every
existing notebook. {"id": "*", "access": "write"} already implies it, so
you only need $root if you want root-level creation without full write
access to everything else. $root only has meaning with access: "write";
an entry for it with access: "read" (or omitted) is a no-op, since there's
nothing to read at the root. It also never grants read or write access to
any real notebook — it's checked before name/id resolution runs, so it
can't collide with an actual notebook, even one literally titled $root.
Two edge cases worth knowing about $root: matching is exact and
case-sensitive (unlike the case-insensitive name matching above), so a typo
like "$Root" won't be recognized as the sentinel — it silently falls
through to normal name/id resolution and matches nothing, rather than
raising an error. And because $root is intercepted before name/id
resolution runs, a real notebook titled $root can no longer be granted
access by name in the notebooks list — use its id instead (from
list_notebooks), same as with any other name collision.
Out-of-scope access raises a NotebookAccessError with a message naming
the notebook, distinct from a JoplinError (an actual Joplin API failure).
Notes on this build
Requires Joplin Desktop running with the Web Clipper service enabled (i.e. Joplin itself must be open — this doesn't run Joplin headlessly).
host/portinconfig.jsonoverride the defaults (localhost/41184) if needed.Errors from the Joplin API surface as
JoplinErrorwith the raw status/body — check these first if a tool call fails.
References
Related projects
Contributing
See CONTRIBUTING.md for development setup, testing, and the release process.
Available Tools
13 toolsappend_note_sectionAppend Note SectionA
Append content to the end of a note's body, without needing to know or resend its existing content. Inserts a blank line separator unless the note is empty or already ends in one.
Inputs: content (required), note_id (required). Returns: result
complete_todoComplete TodoA
Mark a to-do note complete or incomplete. Fails if the note isn't a to-do.
Inputs: note_id (required), completed. Returns: result
create_noteCreate NoteB
Create a new note in the given notebook. Use list_notebooks to find a notebook_id.
Inputs: body (required), title (required), notebook_id (required). Returns: result
create_notebookCreate NotebookA
Create a new notebook. Omit parent_id to create it at the root of the
notebook tree (requires a $root write entry in config, or blanket write
access); set parent_id to nest it inside an existing notebook (requires
write access to that notebook). Use list_notebooks to find a parent_id.
Inputs: title (required), parent_id. Returns: result
delete_noteDelete NoteA
Delete a note by its id. Moves it to Joplin's trash rather than a permanent delete.
Inputs: note_id (required). Returns: result
get_noteGet NoteA
Fetch the full content of a single Joplin note by its id.
Inputs: note_id (required). Returns: result
get_notes_by_tagGet Notes By TagB
List notes with a given tag. Use list_tags to find a tag_id.
Inputs: tag_id (required), limit. Returns: result
list_notebooksList NotebooksA
List all Joplin notebooks (folders) with their ids, for use with create_note.
Inputs: no named parameters. Returns: result
list_notes_in_notebookList Notes In NotebookA
List notes in a notebook without a search query. Use list_notebooks to find a notebook_id.
Inputs: notebook_id (required), limit. Returns: result
list_tagsList TagsA
List all Joplin tags with their ids, for use with get_notes_by_tag.
Inputs: no named parameters. Returns: result
search_notesSearch NotesC
Search Joplin notes by keyword. Returns matching note titles and ids.
Inputs: query (required), limit. Returns: result
update_noteUpdate NoteA
Update an existing note's title and/or body. Only provided fields are
changed, but body, if provided, REPLACES the entire note body - it is
not a patch or append, and any content not included in body is lost.
For a targeted edit to part of a note, use update_note_section; to add
content to the end without resending the whole body, use
append_note_section.
Inputs: note_id (required), body, title. Returns: result
update_note_sectionUpdate Note SectionA
Replace an exact, unique substring within a note's body, without touching the rest of the note. Fails with no write if old_str isn't found, or if it matches more than once - use get_note to find a longer, unique old_str in that case.
Inputs: new_str (required), note_id (required), old_str (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool has a clearly distinct purpose, and the descriptions explicitly disambiguate the tricky trio: update_note (full-body replace), update_note_section (targeted substring), and append_note_section (append). The listing tools (search_notes, list_notes_in_notebook, get_notes_by_tag) are also clearly separated by their input method.
Every tool follows a consistent snake_case verb_noun pattern (search_notes, get_note, create_note, update_note, delete_note, list_notebooks, create_notebook, list_tags, etc.). Suffixes like _section and _in_notebook are applied predictably, so names are fully readable.
13 tools is well-scoped for a note-taking server, giving good granularity between note reads, writes, and structured edits. No tool feels redundant or out of place.
Note lifecycle is fully covered (search/get/create/update/delete plus section edits, todos, and tag listings). However, notebook and tag management is asymmetric: only create_notebook and list_notebooks exist (no update/delete notebook), and tags are read-only with no way to create, delete, or attach a tag to a note.
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
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.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA MCP server for Joplin note-taking application that enables interaction with Joplin notes through the web clipper API, supporting notebook hierarchy and running in Docker.-
- 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-
- AlicenseNot gradedqualityBmaintenanceMCP server for Joplin Server that gives LLMs full access to notes, notebooks, tags, and attachments via the REST API.8MIT
- AlicenseNot gradedqualityCmaintenanceEnables interaction with Joplin notes through MCP, allowing searching, creating, updating, and deleting notes via the Joplin Web Clipper API.6 npmMIT