joplin-mcp

Model Context Protocol (MCP) server for the Joplin note-taking app.

Designed by belsar.ai to be easy to install & enjoyable to use.

Video

https://www.youtube.com/watch?v=B3qJa7ycqNM&t=6s

Platform Support

Available on macOS and Linux. Windows users should use WSL2.

Architecture

By default, this MCP server exposes two tools:

• execute_joplin_readonly_script: For running scripts in read-only mode (inspecting/reading notes and notebooks).
• execute_joplin_script: For running scripts that can also perform modifications, creations, or deletions.

This script-based execution pattern follows Anthropic's recommended pattern for MCP servers and is the most performant, token-efficient way to build an MCP server today.

Scripts execute in a sandboxed runner process, isolated at the OS level — more secure and more performant than a container. The runner cannot access the internet, write to the filesystem, or directly interact with anything on your system.

joplin api ←http→ broker (allowlisted proxy) ←stdio→ runner (sandboxed)

The runner calls joplin.* methods as if talking to Joplin directly, but all requests pass through the broker, which only permits a specific set of API methods. The broker is the only piece that can interact with your notes — and nothing else.

Quick Start

1. Open Joplin & navigate to tools > web clipper > enable web clipper service
2. The Joplin app needs to remain running (minimized is fine)
3. Pick the install command for your platform:

claude mcp add --scope user --transport stdio joplin -- npx -y @belsar-ai/joplin-mcp

codex mcp add joplin -- npx -y @belsar-ai/joplin-mcp

agy plugin install https://github.com/belsar-ai/joplin-mcp

4. That's it. Send a test request like "Find my notes about installing Fedora linux".

Linux Requirements

Install the following system packages before first use:

# Fedora
sudo dnf install bubblewrap socat ripgrep

# Ubuntu/Debian
sudo apt install bubblewrap socat ripgrep

The server will fail with an error message if these are missing.

Uninstall

claude mcp remove joplin

codex mcp remove joplin

agy plugin uninstall joplin-mcp

gemini extensions uninstall joplin-mcp

Configuration (Optional)

Notebook Scope Config

Create .mcp-config/joplin-mcp.toml in your project root to scope which notebooks are visible:

[defaults]
notebook = "Notes"

[scope]
notebooks = ["Notes", "Software"]

• defaults.notebook: Where new notes go if you don't specify a notebook
• scope.notebooks: Only these notebooks are visible to the AI

The config file is discovered by walking up from the current directory (like .git).

Read-Only Lock Mode

You can lock the MCP server down to a strict read-only mode so that no notes or notebooks can be modified, created, or deleted. In this mode, only the execute_joplin_readonly_script tool is exposed to the AI, and any attempts to execute write operations are blocked at the process level.

Configure read-only mode in one of two ways:

1. CLI Flag: Append --readonly to your start command:

   npx -y @belsar-ai/joplin-mcp --readonly
   

2. Environment Variable: Set JOPLIN_READONLY=true (any value other than false, 0, no, off, or empty string will enable lock mode).

Example Usage

The AI can now handle complex requests in a single shot:

Find my notes about installing Arch Linux.

Look for all notes whose last update time was before 2025 and move them to my Archive notebook.

Show me all notes in my Work Projects notebook.

Make a new note with a Mermaid diagram showing how a bill is passed on Capitol Hill.

Working with Large Notes

The AI can navigate, search, and edit large notes without pulling the entire body into context:

Show me the table of contents for my platform docs note.

Show me section 10.1 of my platform docs note.

Search my project plan for "deadline".

Replace "Q3 2025" with "Q4 2025" in my roadmap note.

Available API (Script Context)

The AI has access to a global joplin object with the following methods:

Notes (joplin.notes)

• readNote(id): Pretty-printed note with metadata header and body. Preferred for display.
• getNote(id): Raw note object. Prefer readNote() for display.
• searchNotes(query: string): Smart search with "any:1" logic.
• listAllNotes(fields?, ...): Get all notes.
• createNote(title, body, notebookId, ...): Create a new note.
• updateNote(id, updates): Update properties or body.
• appendToNote(id, text): Add text to the end.
• prependToNote(id, text): Add text to the beginning.
• editNote(id, oldString, newString, replaceAll?): Server-side string replacement. Fails if not found or ambiguous without replaceAll.
• getNoteLineRange(id, startLine, endLine): Read a slice of a note by line number (1-indexed).
• searchInNote(id, pattern): Case-insensitive search within a note. Returns matches with line numbers and context.
• getNoteSections(id): Parse markdown headings into a table of contents with line numbers.
• deleteNote(id): Move to trash.
• moveNoteToNotebook(id, notebookId): Move a note to a different notebook.

Notebooks (joplin.notebooks) — read-only

• listNotebooks(): Get folder structure.
• getNotebook(id): Get a single notebook.
• getNotebookNotes(notebookId, fields?, ...): Get notes in a notebook.
• getNotebookTree(notebookId, depth?): Get formatted tree of a notebook with notes.
• getAllNotebooksTree({ exclude? }): Get formatted tree of all notebooks.
• getScopedTree({ exclude?, depth? }): Get formatted tree of scoped notebooks with notes.

Troubleshooting

• Verify Joplin desktop app is running
• Confirm Web Clipper is enabled in Joplin settings
• Ensure Joplin is listening on port 41184 (default)
• Go outside for a nice walk