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.

<!-- mcp-name: io.github.alondmnt/joplin-mcp -->

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: findnotes (supports trash=True for trashed notes), findnoteswithtag, findnotesinnotebook, getall_notes
• CRUD Operations: getnote, getnoteresources (read OCR text from attached images/PDFs), getlinks, createnote, updatenote, editnote, deletenote

Notebook Management

• Organize: listnotebooks, createnotebook, updatenotebook, deletenotebook

Tag Management

• Categorize: listtags, createtag, updatetag, deletetag, gettagsby_note
• Link: tagnote, untagnote

Trash Management

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

Import

• File Import: importfromfile - 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:
• JOPLINTOKEN: yourjoplinapitoken_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)

Shortened. The full README is on GitHub.