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