joplin-mcp
Provides tools for browsing, searching, creating, updating, and deleting notes and notebooks in Joplin, as well as downloading attachments and extracting OCR text from images/PDFs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@joplin-mcp Search my notes for meeting notes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📓 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.
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 every notebook (folder), with |
| Create a new notebook, optionally nested under a parent |
| Rename and/or move a notebook to a different parent |
| Delete a notebook, including everything inside it (moves it to Joplin's trash) |
| List notes, optionally scoped to one notebook, paginated |
| Full-text search using Joplin's native search syntax ( |
| Fetch a note's full Markdown body + metadata |
| Create a new note (title, Markdown body, target notebook, to-do flag) |
| Rename, edit, and/or move a note (also edits body / to-do status) |
| Delete a note (moves it to Joplin's trash) |
| Get metadata (mime type, extension, size) for an attached file |
| Download an attachment's raw bytes to a local path so it can be opened/viewed |
| 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 |
| ✅ yes | — | Your Web Clipper authorization token |
| no |
| 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? Swapcommand/argsfor"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.1by default (your local Joplin instance) — it's not designed to be exposed over a network.delete_notemoves 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.mdLicense
MIT — see LICENSE.
Available Tools
13 toolscreate_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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Related MCP Servers
- AlicenseAqualityDmaintenanceA 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.696MIT
- FlicenseNot gradedqualityBmaintenanceMCP 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-
- AlicenseAqualityBmaintenanceModel Context Protocol (MCP) server for Joplin note-taking app, enabling AI to read, search, and modify notes via sandboxed scripts.222 npm27Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP server for Joplin Server that gives LLMs full access to notes, notebooks, tags, and attachments via the REST API.8MIT