Content
# 📓 Joplin MCP Server
*A Model Context Protocol server that turns your [Joplin](https://joplinapp.org/) 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](https://joplinapp.org/) 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](https://modelcontextprotocol.io/) 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](https://joplinapp.org/download/)**, running, with the Web Clipper service enabled
- A Joplin **Web Clipper authorization token**
- **Python 3.12+**
- **[uv](https://docs.astral.sh/uv/)** (recommended) — or plain `pip`
---
## Installation
```bash
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):
```json
{
"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](LICENSE).
