Skip to main content
Glama
joplin-mcp

joplin-mcp

by biontdv

📓 Joplin MCP Server

A Model Context Protocol server that turns your Joplin notebook into a tool an LLM can actually use — read, search, write, and organize notes, and pull OCR'd text straight out of your screenshots.

Python License MCP


What is this?

Joplin ships a local Web Clipper / Data API (http://127.0.0.1:41184) that can drive the whole app — notes, notebooks, tags, attachments — over plain HTTP.

This project wraps that API as an MCP server, so any MCP-compatible client (Claude Code, Claude Desktop, or your own agent) can:

  • Browse your notebook tree and list notes inside any notebook

  • Read a note's full Markdown body

  • Full-text search across your entire Joplin database

  • Create, rename, move, and delete both notes and notebooks

  • Download an embedded attachment (screenshot, PDF, PoC file, ...) to disk so it can be viewed

  • Pull OCR-extracted text out of an image/PDF attachment — read what's inside a screenshot without ever opening it

No plugin needs to be installed inside Joplin itself — everything runs through the Data API that's already built in.


Related MCP server: Joplin MCP Server

Features

Tool

What it does

list_notebooks

List every notebook (folder), with id, title, and parent_id

create_notebook

Create a new notebook, optionally nested under a parent

update_notebook

Rename and/or move a notebook to a different parent

delete_notebook

Delete a notebook, including everything inside it (moves it to Joplin's trash)

list_notes

List notes, optionally scoped to one notebook, paginated

search_notes

Full-text search using Joplin's native search syntax (title:, tag:, ...)

get_note

Fetch a note's full Markdown body + metadata

create_note

Create a new note (title, Markdown body, target notebook, to-do flag)

update_note

Rename, edit, and/or move a note (also edits body / to-do status)

delete_note

Delete a note (moves it to Joplin's trash)

get_resource_info

Get metadata (mime type, extension, size) for an attached file

get_resource_file

Download an attachment's raw bytes to a local path so it can be opened/viewed

get_resource_ocr_text

Read back the text Joplin's built-in OCR engine recognized inside an image/PDF attachment


Requirements

  • Joplin desktop, running, with the Web Clipper service enabled

  • A Joplin Web Clipper authorization token

  • Python 3.12+

  • uv (recommended) — or plain pip


Installation

git clone https://github.com/<your-username>/joplin-mcp.git
cd joplin-mcp

# with uv (recommended, uses the committed uv.lock for reproducible installs)
uv sync

# — or with plain pip —
pip install "httpx>=0.28.1" "mcp[cli]>=1.28.1"

1. Enable the Web Clipper service in Joplin

Joplin → Tools → Options → Web Clipper → turn it on. Note the port shown (default 41184).

2. Grab your access token

Same screen → "Advanced options" → "Copy token". Keep this secret — anyone with it has full read/write access to your entire notebook.

3. (Optional) Enable OCR, if you want get_resource_ocr_text to return anything

Joplin → Tools → Options → General → enable "Enable document text extraction (OCR)". Joplin needs some time to process existing attachments after you turn this on — check the ocr_status field returned by the tool (0/1 = queued, 2 = processing, 3 = done, 4 = error, see ocr_error).


Configuration

The server reads two environment variables:

Variable

Required

Default

Description

JOPLIN_TOKEN

✅ yes

—

Your Web Clipper authorization token

JOPLIN_BASE_URL

no

http://127.0.0.1:41184

Base URL of the Joplin Web Clipper API


Usage with an MCP client

Add this to your client's MCP config (e.g. .mcp.json for Claude Code, or the Claude Desktop config file):

{
  "mcpServers": {
    "joplin": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/joplin-mcp", "python", "server.py"],
      "env": {
        "JOPLIN_TOKEN": "<your-joplin-web-clipper-token>",
        "JOPLIN_BASE_URL": "http://127.0.0.1:41184"
      }
    }
  }
}

Running without uv? Swap command/args for "command": "python", "args": ["/absolute/path/to/joplin-mcp/server.py"] instead.

Restart/reconnect your MCP client and the joplin tools should show up.


Example prompts once connected

  • "List my Joplin notebooks."

  • "Search my notes for 'react devtools'."

  • "Pull up the note titled X and summarize it."

  • "Download the screenshot attached to this note so I can look at it."

  • "What text was OCR'd out of that PDF I scanned last week?"


Security notes

  • The Web Clipper token grants full read/write access to your entire Joplin database — treat it like a password. Never commit it to a repo.

  • The server only talks to 127.0.0.1 by default (your local Joplin instance) — it's not designed to be exposed over a network.

  • delete_note moves notes to Joplin's trash (recoverable), unless you've disabled the trash in Joplin's settings.


Known limitations / roadmap

This covers the day-to-day note/notebook/attachment workflow, but doesn't (yet) wrap every corner of Joplin's Data API:

  • ❌ Tags — no list/create/assign tag support

  • ⚠️ Resources — no upload/delete of attachments (only read + OCR text)

  • ❌ Note revision history

PRs welcome if you need one of these.


Project structure

joplin-mcp/
├── server.py         # the MCP server — all tools live here
├── pyproject.toml    # project metadata + dependencies
├── uv.lock           # locked dependency versions (uv)
├── .python-version   # pinned Python version for uv
├── .gitignore
├── LICENSE
└── README.md

License

MIT — see LICENSE.

Available Tools

13 tools
create_noteA

Create a new note.

Args:
    title: Note title.
    body: Note body in Markdown.
    notebook_id: Target notebook (folder) id. If omitted, Joplin uses the
        currently selected notebook in the app.
    is_todo: If true, create the note as a to-do item.

Inputs: title (required), body, is_todo, notebook_id. Returns: object

create_notebookA

Create a new notebook (folder). Use parent_id to nest it under an existing notebook, e.g. a client/project notebook.

Args:
    title: Notebook title.
    parent_id: Parent notebook (folder) id to nest under, if any.

Inputs: title (required), parent_id. Returns: object

delete_noteA

Delete a note by id. In Joplin this moves the note to the trash (or permanently deletes it if the trash is disabled in the app's settings).

Args:
    note_id: The Joplin note id to delete.

Inputs: note_id (required). Returns: result

delete_notebookA

Delete a notebook by id, including all notes and sub-notebooks inside it. In Joplin this moves the notebook to the trash (or permanently deletes it if the trash is disabled in the app's settings).

Args:
    notebook_id: The Joplin notebook (folder) id to delete.

Inputs: notebook_id (required). Returns: result

get_noteA

Fetch a single note's full content (including body) by id.

Args:
    note_id: The Joplin note id.

Inputs: note_id (required). Returns: object

get_resource_fileA

Download a Joplin resource's raw file (e.g. a screenshot embedded in a note) and save it to a local path, so it can then be viewed with a file-reading tool. Call get_resource_info first if you need the mime type to choose the save_path's extension.

Args:
    resource_id: The Joplin resource id (from a note body link like ':/<id>').
    save_path: Absolute local file path to save the downloaded file to.

Inputs: save_path (required), resource_id (required). Returns: object

get_resource_infoA

Fetch metadata for a Joplin resource (an attachment/image embedded in a note body, referenced there as ':/<resource_id>'), including its mime type and file extension. Use this before get_resource_file to pick a sensible file extension for the saved file.

Args:
    resource_id: The Joplin resource id.

Inputs: resource_id (required). Returns: object

get_resource_ocr_textA

Fetch the OCR-extracted text for a Joplin resource (e.g. text recognized inside a screenshot or scanned PDF/image attachment), without downloading the file itself. Requires Joplin's built-in OCR feature to be enabled (Options > General > "Enable document text extraction") and to have finished processing the resource.

The returned `ocr_status` is one of: 0=not queued yet, 1=queued/todo,
2=processing, 3=done, 4=error (see `ocr_error` if it failed). If OCR
hasn't finished yet, retry after a short delay.

Note: Joplin also automatically indexes ocr_text for full-text search,
so search_notes may already surface hits found only inside an image via
OCR without needing this tool.

Args:
    resource_id: The Joplin resource id (from a note body link like ':/<id>').

Inputs: resource_id (required). Returns: object

list_notebooksA

List all Joplin notebooks (folders), with id, title and parent_id.

Inputs: no named parameters. Returns: result

list_notesA

List notes, optionally filtered to a single notebook.

Args:
    notebook_id: If set, only return notes inside this notebook (folder id).
    limit: Max notes per page (Joplin caps this at 100).
    page: Page number, starting at 1.

Inputs: page, limit, notebook_id. Returns: object

search_notesA

Full-text search notes using Joplin's search syntax (e.g. 'title:foo', 'tag:bar').

Args:
    query: Search query string.
    limit: Max results per page (Joplin caps this at 100).
    page: Page number, starting at 1.

Inputs: query (required), page, limit. Returns: object

update_noteA

Edit an existing note. Only the fields provided are changed.

Args:
    note_id: The Joplin note id to edit.
    title: New title, if changing it.
    body: New Markdown body, if changing it (replaces the whole body).
    notebook_id: Move the note to this notebook id, if changing it.
    is_todo: Convert to/from a to-do item, if changing it.
    todo_completed: Mark a to-do complete/incomplete, if changing it.

Inputs: note_id (required), body, title, is_todo, +2 more. Returns: object

update_notebookA

Rename and/or move a notebook. Only the fields provided are changed.

Args:
    notebook_id: The Joplin notebook (folder) id to edit.
    title: New title, if renaming it.
    parent_id: New parent notebook id, if moving it. Pass an empty string
        to move it to the top level (no parent).

Inputs: notebook_id (required), title, parent_id. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: notebooks (create/list/update/delete), notes (create/get/list/update/delete/search), and resources (info/file/OCR). There is no overlap in purpose, and descriptions clearly distinguish similar operations like get_note vs list_notes.

    Naming Consistency5/5

    All tool names follow the same verb_noun pattern in snake_case (e.g., create_notebook, list_notes, get_resource_file). Pluralization is consistent for list operations, and verbs are uniform across resource types.

    Tool Count5/5

    With 13 tools, the surface is well-scoped for a note-taking domain: full CRUD for notebooks and notes, plus search and resource handling. Each tool serves a clear purpose without unnecessary bloat.

    Completeness4/5

    The set covers all core note and notebook operations (create, read, update, delete, list, search), and resource retrieval is handled. Minor gaps exist: no single-notebook getter and no resource listing/deletion, but these are non-critical and agents can work around them.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A server that enables AI assistants to access and manipulate Joplin notes through the Model Context Protocol, allowing search, reading, editing, and management of notes using natural language.
      6
      96
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP server that provides standardized tools for querying and retrieving notes from Joplin personal knowledge manager through its API, enabling AI assistants to access and reference personal notes contextually.
      9
      -
    • A
      license
      A
      quality
      B
      maintenance
      Model Context Protocol (MCP) server for Joplin note-taking app, enabling AI to read, search, and modify notes via sandboxed scripts.
      2
      22 npm
      27
      Apache 2.0