Joplin MCP Server

MCP (Model Context Protocol) server for Joplin Notes integration, allowing AI assistants to manage your notes, notebooks, and tags.

Features

• Notes: List, create, update, search, and delete notes

• Notebooks: List and create notebooks (folders)

• Tags: List tags and tag notes

• Search: Full Joplin search syntax support

• To-dos: Create and manage to-do items

Prerequisites

• Joplin desktop app must be running

• Web Clipper service must be enabled

Setup

1. Enable Web Clipper in Joplin

1. Open Joplin desktop

2. Go to Tools → Options → Web Clipper

3. Click Enable Web Clipper Service

4. Copy the Authorization token

2. Install Dependencies

cd repos/joplin-mcp
uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt

3. Configure Claude Code

Add to your Claude Code MCP settings (~/.claude/mcp_settings.json):

{
  "mcpServers": {
    "joplin": {
      "command": "/home/samuel/repos/joplin-mcp/.venv/bin/python",
      "args": ["/home/samuel/repos/joplin-mcp/joplin_mcp.py"],
      "env": {
        "JOPLIN_TOKEN": "your-api-token-here"
      }
    }
  }
}

Available Tools

Usage Examples

Once configured, you can ask Claude:

• "Show me my Joplin notebooks"

• "List my recent notes"

• "Create a note called 'Meeting Notes' in my Work notebook"

• "Search for notes about 'project plan'"

• "What notes are tagged with 'important'?"

Search Syntax

The joplin_search_notes tool supports Joplin's query syntax:

• title:meeting - Search in title

• body:action items - Search in body

• tag:work - Filter by tag

• notebook:Projects - Filter by notebook

• type:todo - Only to-dos

• iscompleted:0 - Incomplete to-dos

• created:20240101 - Created after date

• updated:20240101 - Updated after date

Combine: tag:work type:todo iscompleted:0 finds incomplete work todos.

Note

Joplin desktop must be running for the MCP server to work. The API connects to localhost:41184 (the Web Clipper service).

License

MIT