📓 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.

---

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.