Joplin MCP Server

Joplin MCP Server

A FastMCP-based Model Context Protocol (MCP) server for Joplin note-taking application via its Python API joppy, enabling AI assistants to interact with your Joplin notes, notebooks, and tags through a standardized interface.

Table of Contents

• What You Can Do
• Quick Start
• Supported Clients
• Example Usage
• Tool Permissions
• Notebook Allowlist
• Advanced Configuration
• Docker
• Project Structure
• Testing
• Complete Tool Reference
• Changelog

What You Can Do

This MCP server provides 26 optimized tools for comprehensive Joplin integration:

Note Management

• Find & Search: find_notes (supports trash=True for trashed notes), find_notes_with_tag, find_notes_in_notebook, get_all_notes
• CRUD Operations: get_note, get_note_resources (read OCR text from attached images/PDFs), get_links, create_note, update_note, edit_note, delete_note

Notebook Management

• Organize: list_notebooks, create_notebook, update_notebook, delete_notebook

Tag Management

• Categorize: list_tags, create_tag, update_tag, delete_tag, get_tags_by_note
• Link: tag_note, untag_note

Trash Management

• Recover: restore_from_trash - Restore soft-deleted notes or notebooks

Import

• File Import: import_from_file - Import Markdown, HTML, CSV, TXT, JEX files and directories

System

• Health: ping_joplin

Quick Start

1. Open Joplin Desktop → Tools → Options → Web Clipper
2. Enable the Web Clipper service
3. Copy the Authorization token
4. Set up your preferred client below

Supported Clients

Any MCP-compatible client should work. Below are the ones with documented setup instructions.

Claude Desktop

Run the automated installer:

# Install and configure everything automatically (pip)

pip install joplin-mcp joplin-mcp-install

Or use zero-install with uvx (recommended if you have uv)

uvx --from joplin-mcp joplin-mcp-install

Optional: pin a specific version/range for stability

uvx --from joplin-mcp==0.4.1 joplin-mcp-install uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install

This script will:

• Configure your Joplin API token
• Set tool permissions (Create/Update/Delete)
• Set up Claude Desktop automatically
• Test the connection

After setup, restart Claude Desktop and you're ready to go!

Claude Code

Install the orchestration plugin for smarter tool usage (edit vs update, long-note reading, bulk tagging):

/plugin marketplace add alondmnt/joplin-mcp

/plugin install joplin-mcp

You'll be prompted for your Joplin API token on first use. The skill is invoked automatically when working with Joplin tools, or manually with /joplin.

Jan AI

1. Install Jan AI from https://jan.ai

1. Add MCP Server in Jan's interface:

• Open Jan AI
• Go to Settings → Extensions → Model Context Protocol
• Click Add MCP Server
• Configure:
• Name: joplin
• Command: uvx --from joplin-mcp joplin-mcp-server *(requires uv installed)*
• Environment Variables:
• JOPLIN_TOKEN: your_joplin_api_token_here
• Enable the server

1. Start chatting with access to your Joplin notes!

Automated Setup (Alternative)

# Install and configure Jan AI automatically (if Jan is already installed)

pip install joplin-mcp joplin-mcp-install

This will detect and configure Jan AI automatically, just like Claude Desktop.

OllMCP (Local Ollama Models)

Auto-discovery (if you set up Claude Desktop first)

# Install ollmcp

pip install ollmcp

Run with auto-discovery (requires existing Claude Desktop config)

ollmcp --auto-discovery --model qwen3:4b

Manual setup (works independently)

# Install ollmcp

pip install ollmcp

Set environment variable

export JOPLIN_TOKEN="your_joplin_api_token_here"

Run with uvx (requires uv installed)

ollmcp --server "joplin:uvx --from joplin-mcp joplin-mcp-server" --model qwen3:4b

Or with an installed package (pip install joplin-mcp)

ollmcp --server "joplin:joplin-mcp-server" --model qwen3:4b

Example Usage

Once configured, you can ask your AI assistant:

• "List all my notebooks" - See your Joplin organization
• "Find notes about Python programming" - Search your knowledge base
• "Create a meeting note for today's standup" - Quick note creation
• "Tag my recent AI notes as 'important'" - Organize with tags
• "Show me my todos" - Find task items with find_notes(task=True)

Tool Permissions

The setup script offers 4 permission levels:

• Read (always enabled): Browse and search your notes safely
• Write (optional): Create new notes, notebooks, and tags
• Update (optional): Modify existing content
• Delete (optional): Remove content permanently

Choose the level that matches your comfort and use case.

Notebook Allowlist

Restrict AI access to specific notebooks using pattern-based access control. When configured, only matching notebooks (and their contents) are visible — all other notebooks are hidden.

Quick Setup

JSON config (joplin-mcp.json):

{

"token": "your_token", "notebook_allowlist": ["Work", "Projects/Public"] }

Environment variable:

export JOPLIN_NOTEBOOK_ALLOWLIST="Work,Projects/Public"

Pattern Syntax

Patterns use gitignore/gitwildmatch semantics:

Negation patterns always win over positive patterns (any negation match on a path or ancestor denies access).

How It Works

• Hierarchical access: Allowing a parent notebook grants access to all its children. Allowing Projects means notes in Projects/Work/Tasks are also accessible.
• Read protection: get_note, get_note_resources, find_notes, get_links — notes in blocked notebooks are filtered out or rejected.
• Write protection: create_note, update_note, edit_note, delete_note — operations on notes in blocked notebooks are rejected.
• Notebook operations: list_notebooks only shows accessible notebooks. create_notebook is rejected both under a blocked parent and at the top level (no parent_name) when an allowlist is set, and update_notebook rejects moves to top-level (parent_name="/") under the same policy — both would let the agent silently move a notebook out of allowlist-enforced scope. To grow the allowlist, create or relocate the notebook in the Joplin UI, then add it to notebook_allowlist and restart the server.
• Search filtering: find_notes results are filtered to only include notes in accessible notebooks.
• Tag operations: tag_note, untag_note, get_tags_by_note enforce access on the note's notebook.
• Error privacy: Blocked access raises a generic "Notebook not accessible" error without revealing notebook names or IDs.

Configuration Examples

Single project focus (notebook name containing a space):

{ "notebook_allowlist": ["Work Projects"] }

Multiple notebooks with exclusion:

{ "notebook_allowlist": ["Projects", "!Projects/Secret", "AI", "Reference"] }

Glob patterns:

{ "notebook_allowlist": ["Projects/*", "!Projects/Private"] }

No allowlist (default) — all notebooks accessible:

{ "notebook_allowlist": null }

Startup Behavior

At server startup, the allowlist is validated and logged:

• Each entry is resolved against existing notebooks
• Unresolvable patterns trigger warnings (but never block startup)
• If the allowlist resolves to zero accessible notebooks, a warning is logged

---

Advanced Configuration

Development Installation

For developers or users who want the latest features:

git clone https://github.com/alondmnt/joplin-mcp.git

cd joplin-mcp python bootstrap.py

bootstrap.py is cross-platform: it offers to create a ./venv, runs pip install -e ., then launches the interactive installer. Pass --no-venv to install into whichever Python is already active.

Manual Configuration

If you prefer manual setup or the script doesn't work:

Note on uvx: uvx runs Python applications without permanently installing them (requires uv: pip install uv). It can read and write user configuration files (e.g., Claude/Jan configs), so uvx --from joplin-mcp joplin-mcp-install works for setup just like a pip install.

Version pinning (optional): For long‑lived client configs or CI, you can pin or range-constrain the version for reproducibility, e.g. uvx --from joplin-mcp==0.4.1 joplin-mcp-install or uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install.

1. Create Configuration File

Create joplin-mcp.json in your project directory:

{

"token": "your_api_token_here", "host": "localhost", "port": 41184, "timeout": 30, "verify_ssl": false }

2. Claude Desktop Configuration

Add to your claude_desktop_config.json:

Option A: Using uvx (Zero-install)

{

"mcpServers": { "joplin": { "command": "uvx", "args": ["--from", "joplin-mcp", "joplin-mcp-server"], "env": { "JOPLIN_TOKEN": "your_token_here" } } } }

*Requires `uv` installed: `pip install uv`*

Option B: Using installed package

{

"mcpServers": { "joplin": { "command": "joplin-mcp-server", "env": { "JOPLIN_TOKEN": "your_token_here" } } } }

3. More Client Configuration Examples

For additional client configurations including different transport options (HTTP, SSE, Streamable HTTP), see client-config.json.example.

This file includes configurations for:

• STDIO transport (default, most compatible)
• HTTP transport (basic HTTP server mode)
• SSE transport (recommended for gemini-cli and OpenAI clients)
• Streamable HTTP transport (advanced web clients)
• HTTP-compat transport (bridges modern /mcp JSON-RPC with legacy /sse//messages clients)

Tool Permission Configuration

Fine-tune which operations the AI can perform by editing your config:

{

"tools": { "create_note": true, "update_note": true, "delete_note": false, "create_notebook": true, "update_notebook": false, "delete_notebook": false, "create_tag": true, "update_tag": false, "delete_tag": false, "get_all_notes": false, "import_from_file": true } }

Environment Variables

Usable instead of a JSON config file, or alongside one:

# Connection settings

export JOPLIN_TOKEN="your_api_token_here" export JOPLIN_HOST="localhost" export JOPLIN_PORT="41184" export JOPLIN_TIMEOUT="30"

Environment variables override the config file key by key, so the env block in your MCP client's configuration wins over whatever file the server discovers. A variable only takes part when it is actually set, so setting one leaves the rest of your file alone. Full order: direct parameters > environment > config file > defaults.

Per-Tool Env Vars

Every tool can be toggled individually via JOPLIN_TOOL_ =true|false. These take