AI agents and Joplin

Apps
8

Over the past few months multiple MCP servers for Joplin have been released. With the recent addition of belsar-ai/joplin-mcp, which looks quite impressive, I co-wrote with ChatGPT an overview of the existing MCPs (sorry if I missed any). In order to stay balanced, I asked ChatGPT to crawl over the GitHub repos of these MCPs and extract their features. In my opinion, there is no single “ultimate” MCP, and we probably would have benefited from combining our efforts into a single project (if we could bridge the TS / Python split). But since it’s not very hard to build one, each developer (myself included) ended up building their own server from scratch, tailored to their own taste.

It could be interesting at some point to create a benchmark for personal knowledge management in order to evaluate these servers and their tools, and to understand better what patterns work best with LLMs and Joplin.

Disclosure: I’m the maintainer of alondmnt/joplin-mcp. I’ve tried to describe all projects as neutrally as possible; corrections from other maintainers are very welcome.

TL;DR

  • There are now several Joplin MCP servers; they differ in scope (notes vs tags/notebooks vs attachments/revisions) and in how they handle context size / filtered content.
  • Some focus on simple CRUD or read-only search, others try to expose more of Joplin’s structure (tags, links, resources, revisions).
  • There is no single best one: depending on your use-case you might care more about attachments, privacy / context control, read-only safety, or just simplicity.

High-level comparison

“Filtered/context features” = anything that helps the AI not pull huge amounts of text unnecessarily (previews, metadata-only listings, pagination, line ranges, etc).

Server Stack / API Main scope Distinctive bits Filtered / context features (brief)
alondmnt/joplin-mcp Python, FastMCP, uses Joppy (Python Joplin API) Notes, notebooks, tags, optional import Higher-level note tools: find_notes_*, find_in_note (regex in-note), get_links (note links + backlinks), get_note with sections, TOC, and sequential reading; per-tool permissions; multiple transports (STDIO / HTTP / SSE). import_from_file can import files or directories (md/html/csv/jex/generic), supports CSV modes/options, rewrites note links to internal Joplin links, and uploads resources/attachments as part of the import. Global content-exposure policy: search/listings/individual notes can be set to none / preview / full, with a configurable max_preview_length. get_note can return TOC only, metadata only, or specific line ranges, which helps keep long notes manageable.
belsar-ai/joplin-mcp TypeScript / Node, Web Clipper API Notes, notebooks, tags, resources, revisions Broad Joplin API coverage: tools for attachments/resources (list, metadata, download/upload, update, delete) and revision history; many “filtered retrieval” tools (by notebook, tag, resource, etc.). Server description includes explicit search/discovery strategy for the LLM. Many list/filtered tools accept fields, limit and sorting, so the client can request metadata-only (e.g. id,title,updated_time) or smaller subsets instead of full note bodies. No global preview policy; it’s per-call and driven by how the client uses fields/limit.
jakubfrieb/mcp-joplin Node.js (JS), Web Clipper API Read-only notes + notebooks One of the earlier servers. Tools: list_notebooks, search_notes, read_notebook, read_note, read_multinote. Designed around a “search → then read” workflow, with good logging and clear examples. search_notes returns snippets plus note + notebook IDs; the recommended pattern is search_notes → feed selected IDs into read_multinote, which is context-friendlier than reading everything. Still returns full note bodies when reading; no explicit preview/length knobs.
alexey-temnikov/mcp-joplin TypeScript / Node, Web Clipper API Notes + basic notebooks Straightforward server with read_multinote and import_markdown. Encourages a similar staged “search → pick note IDs → batch read” workflow, with nice docs and logging. Staged retrieval (search → read_multinote) plus numeric limits. As with jakubfrieb’s server, context control comes from how you chain the tools, not from preview/TOC features.
happyeric77/mcp-joplin TypeScript / Node, Web Clipper API Notes + notebooks Adds scan_unchecked_items to find unchecked todos across notebooks; includes create/delete/move tools for notes and notebooks. Geared toward “review my tasks in this notebook tree” type use. List/search tools support basic limit. scan_unchecked_items gives a condensed view of incomplete tasks; when you fetch a note, you typically get full content. No explicit previews/sections.
dweigend/joplin-mcp-server Python, Web Clipper API Notes only Notes-only server: full-text search, read, create/update, delete (trash or permanent), plus import_markdown. Aimed at simple Claude/AI integration with uv-based setup. Search/list tools take a limit to cap result count; individual notes are returned in full. Context control is mostly “search first, then read a small number of specific notes.”
Darkflib/mcp-joplin Python, Web Clipper API Read-only notes + notebooks Read-only by design with rate limiting and tests. Good if you want an AI to search and navigate your notes but never modify them. Safety is primarily “no write tools” + rate limiting. Retrieval returns full note content for selected notes; there’s no extra preview/TOC layer, but you can’t accidentally edit anything.

This is intentionally simplified; several of these repos have more tools than fit in one row.

Which one might you want?

Very very roughly:

Zoom-in: filtered content & note-level design

(alondmnt/joplin-mcp vs belsar-ai/joplin-mcp)

Two extensive MCPs, with different design choices around note reading, filtered content, and resources. This section isn’t about “better/worse”, just surfacing the differences.

Note-level tools & content

Aspect alondmnt/joplin-mcp belsar-ai/joplin-mcp
Finding notes “Top-level” search tools in the docstring: find_notes (text or list all, paginated), find_notes_with_tag, find_notes_in_notebook – explicitly marked as the main functions for text, tag, and notebook searches. Multiple listing/filtered tools: notes by notebook, notes by tag, notes attached to a resource, notes in a revision chain, etc., generally with limit and sorting. Very API-like filtered retrieval.
Smart note reading get_note has “smart display”: short notes → full content, long notes → TOC by default. Supports section= (by heading text/slug/number), toc_only, metadata_only, force_full, plus sequential reading via start_line + line_count. get_note just returns the note as stored in Joplin; logic like “only show part of this” or “treat long notes differently” is left to the client/model.
In-note search find_in_note runs regex search inside a single note with limit + offset and flags (case_sensitive, multiline, dotall), returning paginated matches with context. No dedicated in-note search tool; you’d usually get_note and then search inside it with the LLM.
Links / graph features get_links parses note links of the form [text](:/noteId[#section]) and returns outgoing links and backlinks, including section slugs and line context, effectively exposing the note graph. No note link-graph tools, but strong attachment graph support via tools like get_note_attachments and get_resource_notes (notes ↔ resources).
Attachments & revisions Focus is notes/notebooks/tags plus import. There is no general “resource CRUD” surface, but import_from_file will import attachments/resources and convert note links to internal Joplin links when bringing in files/directories (mixed formats and RAW exports). Strong ongoing support: list/get/update/delete resources, download/upload attachments, plus list/get revisions. Good if you want to programmatically inspect and manage files and history in an existing vault.

Context, privacy & filtering

Aspect alondmnt/joplin-mcp belsar-ai/joplin-mcp
Content exposure policy Global settings for search_results, individual_notes and listings: each can be none, preview, or full, plus a max_preview_length. This acts as a policy layer over what tools are allowed to return (e.g. “search results = previews only”). Many list/“filtered” tools support a fields parameter so the client can request metadata-only (id,title,updated_time, etc.) or include/exclude body, and limit to cap counts. There’s no single global exposure flag; it’s per-call via fields/limit.
Pagination / incremental reading Search tools use limit + offset; find_in_note is paginated; get_note supports line-range reading with start_line + line_count. That makes it easier to step through long notes gradually. List tools use limit and sorting (order_by, order_dir); pagination is mainly “top N by some ordering”. No built-in line-range reading for individual notes.
Tool permissions & safety Configurable per-tool permissions (e.g. enable/disable create_note, delete_note, get_all_notes, import_from_file). Some “heavy” tools like get_all_notes and import_from_file are disabled by default. Some destructive operations (e.g. deleting resources) perform runtime checks before acting (for example, listing notes that still use the resource and warning instead of immediately deleting). All tools are generally available once the server is configured.

Caveats

  • This is just a snapshot based on the public repos at the time of writing; things will definitely evolve.
  • I tried to stick to documented behaviour (and obvious code paths) rather than guessing about internals.
  • If you maintain any of these projects (or have one I missed), please feel free to jump in with corrections, clarifications, or additional features—especially around context/filtered-content behaviour or new tools.