Skip to content
Back to search

joplin-mcp

MCP server for the Joplin note taking app

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alondmnt--joplin-mcp/badge.svg)](/listings/alondmnt--joplin-mcp)

HTML

<a href="/listings/alondmnt--joplin-mcp"><img src="/api/listings/alondmnt--joplin-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**JSON config** (`joplin-mcp.json`):

{
  "token": "your_token",
  "notebook_allowlist": ["Work", "Projects/Public"]
}

**Environment variable**:

export JOPLIN_NOTEBOOK_ALLOWLIST="Work,Projects/Public"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "joplin-mcp",
  4. "metadata": {
  5. "description": "Joplin note-management tools for Claude Code"
  6. },
  7. "owner": {
  8. "name": "Alon Diament"
  9. },
  10. "plugins": [
  11. {
  12. "name": "joplin-mcp",
  13. "description": "Orchestration skill for 26 Joplin note-management tools — smart edit vs update, long-note reading, bulk tagging",
  14. "version": "0.10.0",
  15. "author": {
  16. "name": "Alon Diament"
  17. },
  18. "source": "./",
  19. "category": "productivity"
  20. }
  21. ]
  22. }
README.md · README · 619 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Joplin MCP Server
  2. A **FastMCP-based Model Context Protocol (MCP) server** for [Joplin](https://joplinapp.org/) note-taking application via its Python API [joppy](https://github.com/marph91/joppy), enabling AI assistants to interact with your Joplin notes, notebooks, and tags through a standardized interface.
  3. <!-- mcp-name: io.github.alondmnt/joplin-mcp -->
  4. ## Table of Contents
  5. - [What You Can Do](#what-you-can-do)
  6. - [Quick Start](#quick-start)
  7. - [Supported Clients](#supported-clients)
  8. - [Example Usage](#example-usage)
  9. - [Tool Permissions](#tool-permissions)
  10. - [Notebook Allowlist](#notebook-allowlist)
  11. - [Advanced Configuration](#advanced-configuration)
  12. - [Docker](#docker)
  13. - [Project Structure](#project-structure)
  14. - [Testing](#testing)
  15. - [Complete Tool Reference](#complete-tool-reference)
  16. - [Changelog](CHANGELOG.md)
  17. ## What You Can Do
  18. This MCP server provides **26 optimized tools** for comprehensive Joplin integration:
  19. ### **Note Management**
  20. - **Find & Search**: `find_notes` (supports `trash=True` for trashed notes), `find_notes_with_tag`, `find_notes_in_notebook`, `get_all_notes`
  21. - **CRUD Operations**: `get_note`, `get_note_resources` (read OCR text from attached images/PDFs), `get_links`, `create_note`, `update_note`, `edit_note`, `delete_note`
  22. ### **Notebook Management**
  23. - **Organize**: `list_notebooks`, `create_notebook`, `update_notebook`, `delete_notebook`
  24. ### **Tag Management**
  25. - **Categorize**: `list_tags`, `create_tag`, `update_tag`, `delete_tag`, `get_tags_by_note`
  26. - **Link**: `tag_note`, `untag_note`
  27. ### **Trash Management**
  28. - **Recover**: `restore_from_trash` - Restore soft-deleted notes or notebooks
  29. ### **Import**
  30. - **File Import**: `import_from_file` - Import Markdown, HTML, CSV, TXT, JEX files and directories
  31. ### **System**
  32. - **Health**: `ping_joplin`
  33. ## Quick Start
  34. 1. Open **Joplin Desktop** → **Tools** → **Options** → **Web Clipper**
  35. 2. **Enable** the Web Clipper service
  36. 3. **Copy** the Authorization token
  37. 4. Set up your preferred client below
  38. ## Supported Clients
  39. > Any MCP-compatible client should work. Below are the ones with documented setup instructions.
  40. ### Claude Desktop
  41. Run the automated installer:
  42. ```bash
  43. # Install and configure everything automatically (pip)
  44. pip install joplin-mcp
  45. joplin-mcp-install
  46. # Or use zero-install with uvx (recommended if you have uv)
  47. uvx --from joplin-mcp joplin-mcp-install
  48. # Optional: pin a specific version/range for stability
  49. uvx --from joplin-mcp==0.4.1 joplin-mcp-install
  50. uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install
  51. ```
  52. This script will:
  53. - Configure your Joplin API token
  54. - Set tool permissions (Create/Update/Delete)
  55. - Set up Claude Desktop automatically
  56. - Test the connection
  57. After setup, restart Claude Desktop and you're ready to go!
  58. ### Claude Code
  59. Install the orchestration plugin for smarter tool usage (edit vs update, long-note reading, bulk tagging):
  60. ```bash
  61. /plugin marketplace add alondmnt/joplin-mcp
  62. /plugin install joplin-mcp
  63. ```
  64. You'll be prompted for your Joplin API token on first use. The skill is invoked automatically when working with Joplin tools, or manually with `/joplin`.
  65. ### Jan AI
  66. 1. **Install Jan AI** from [https://jan.ai](https://jan.ai)
  67. 2. **Add MCP Server** in Jan's interface:
  68. - Open Jan AI
  69. - Go to **Settings** → **Extensions** → **Model Context Protocol**
  70. - Click **Add MCP Server**
  71. - Configure:
  72. - **Name**: `joplin`
  73. - **Command**: `uvx --from joplin-mcp joplin-mcp-server` *(requires `uv` installed)*
  74. - **Environment Variables**:
  75. - `JOPLIN_TOKEN`: `your_joplin_api_token_here`
  76. - Enable the server
  77. 3. **Start chatting** with access to your Joplin notes!
  78. **Automated Setup (Alternative)**
  79. ```bash
  80. # Install and configure Jan AI automatically (if Jan is already installed)
  81. pip install joplin-mcp
  82. joplin-mcp-install
  83. ```
  84. This will detect and configure Jan AI automatically, just like Claude Desktop.
  85. ### OllMCP (Local Ollama Models)
  86. **Auto-discovery (if you set up Claude Desktop first)**
  87. ```bash
  88. # Install ollmcp
  89. pip install ollmcp
  90. # Run with auto-discovery (requires existing Claude Desktop config)
  91. ollmcp --auto-discovery --model qwen3:4b
  92. ```
  93. **Manual setup (works independently)**
  94. ```bash
  95. # Install ollmcp
  96. pip install ollmcp
  97. # Set environment variable
  98. export JOPLIN_TOKEN="your_joplin_api_token_here"
  99. # Run with uvx (requires uv installed)
  100. ollmcp --server "joplin:uvx --from joplin-mcp joplin-mcp-server" --model qwen3:4b
  101. # Or with an installed package (pip install joplin-mcp)
  102. ollmcp --server "joplin:joplin-mcp-server" --model qwen3:4b
  103. ```
  104. ## Example Usage
  105. Once configured, you can ask your AI assistant:
  106. - **"List all my notebooks"** - See your Joplin organization
  107. - **"Find notes about Python programming"** - Search your knowledge base
  108. - **"Create a meeting note for today's standup"** - Quick note creation
  109. - **"Tag my recent AI notes as 'important'"** - Organize with tags
  110. - **"Show me my todos"** - Find task items with `find_notes(task=True)`
  111. ## Tool Permissions
  112. The setup script offers **4 permission levels**:
  113. - **Read** (always enabled): Browse and search your notes safely
  114. - **Write** (optional): Create new notes, notebooks, and tags
  115. - **Update** (optional): Modify existing content
  116. - **Delete** (optional): Remove content permanently
  117. Choose the level that matches your comfort and use case.
  118. ## Notebook Allowlist
  119. Restrict AI access to specific notebooks using pattern-based access control. When configured, only matching notebooks (and their contents) are visible — all other notebooks are hidden.
  120. ### Quick Setup
  121. **JSON config** (`joplin-mcp.json`):
  122. ```json
  123. {
  124. "token": "your_token",
  125. "notebook_allowlist": ["Work", "Projects/Public"]
  126. }
  127. ```
  128. **Environment variable**:
  129. ```bash
  130. export JOPLIN_NOTEBOOK_ALLOWLIST="Work,Projects/Public"
  131. ```
  132. ### Pattern Syntax
  133. Patterns use [gitignore/gitwildmatch](https://git-scm.com/docs/gitignore) semantics:
  134. | Pattern | Matches | Example |
  135. |---------|---------|---------|
  136. | `Work` | Exact notebook name (and all children) | `Work`, `Work/Tasks`, `Work/Notes` |
  137. | `Projects/*` | Direct children of Projects | `Projects/Alpha`, `Projects/Beta` |
  138. | `Projects/**` | All descendants recursively | `Projects/Alpha/Tasks/Q1` |
  139. | `!Projects/Secret` | Exclude (negate) a specific path | Everything in Projects *except* Secret |
  140. Negation patterns always win over positive patterns (any negation match on a path or ancestor denies access).
  141. ### How It Works
  142. - **Hierarchical access**: Allowing a parent notebook grants access to all its children. Allowing `Projects` means notes in `Projects/Work/Tasks` are also accessible.
  143. - **Read protection**: `get_note`, `get_note_resources`, `find_notes`, `get_links` — notes in blocked notebooks are filtered out or rejected.
  144. - **Write protection**: `create_note`, `update_note`, `edit_note`, `delete_note` — operations on notes in blocked notebooks are rejected.
  145. - **Notebook operations**: `list_notebooks` only shows accessible notebooks. `create_notebook` is rejected both under a blocked parent and at the top level (no `parent_name`) when an allowlist is set, and `update_notebook` rejects moves to top-level (`parent_name="/"`) under the same policy — both would let the agent silently move a notebook out of allowlist-enforced scope. To grow the allowlist, create or relocate the notebook in the Joplin UI, then add it to `notebook_allowlist` and restart the server.
  146. - **Search filtering**: `find_notes` results are filtered to only include notes in accessible notebooks.
  147. - **Tag operations**: `tag_note`, `untag_note`, `get_tags_by_note` enforce access on the note's notebook.
  148. - **Error privacy**: Blocked access raises a generic "Notebook not accessible" error without revealing notebook names or IDs.
  149. ### Configuration Examples
  150. **Single project focus** (notebook name containing a space):
  151. ```json
  152. { "notebook_allowlist": ["Work Projects"] }
  153. ```
  154. **Multiple notebooks with exclusion:**
  155. ```json
  156. { "notebook_allowlist": ["Projects", "!Projects/Secret", "AI", "Reference"] }
  157. ```
  158. **Glob patterns:**
  159. ```json
  160. { "notebook_allowlist": ["Projects/*", "!Projects/Private"] }
  161. ```
  162. **No allowlist (default)** — all notebooks accessible:
  163. ```json
  164. { "notebook_allowlist": null }
  165. ```
  166. ### Startup Behavior
  167. At server startup, the allowlist is validated and logged:
  168. - Each entry is resolved against existing notebooks
  169. - Unresolvable patterns trigger warnings (but never block startup)
  170. - If the allowlist resolves to zero accessible notebooks, a warning is logged
  171. ---
  172. ## Advanced Configuration
  173. ### Development Installation
  174. For developers or users who want the latest features:
  175. ```bash
  176. git clone https://github.com/alondmnt/joplin-mcp.git
  177. cd joplin-mcp
  178. python bootstrap.py
  179. ```
  180. `bootstrap.py` is cross-platform: it offers to create a `./venv`, runs `pip install -e .`, then launches the interactive installer. Pass `--no-venv` to install into whichever Python is already active.
  181. ### Manual Configuration
  182. If you prefer manual setup or the script doesn't work:
  183. > Note on `uvx`: `uvx` runs Python applications without permanently installing them (requires `uv`: `pip install uv`). It can read and write user configuration files (e.g., Claude/Jan configs), so `uvx --from joplin-mcp joplin-mcp-install` works for setup just like a pip install.
  184. > Version pinning (optional): For long‑lived client configs or CI, you can pin or range-constrain the version for reproducibility, e.g. `uvx --from joplin-mcp==0.4.1 joplin-mcp-install` or `uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install`.
  185. #### 1. Create Configuration File
  186. Create `joplin-mcp.json` in your project directory:
  187. ```json
  188. {
  189. "token": "your_api_token_here",
  190. "host": "localhost",
  191. "port": 41184,
  192. "timeout": 30,
  193. "verify_ssl": false
  194. }
  195. ```
  196. #### 2. Claude Desktop Configuration
  197. Add to your `claude_desktop_config.json`:
  198. **Option A: Using uvx (Zero-install)**
  199. ```json
  200. {
  201. "mcpServers": {
  202. "joplin": {
  203. "command": "uvx",
  204. "args": ["--from", "joplin-mcp", "joplin-mcp-server"],
  205. "env": {
  206. "JOPLIN_TOKEN": "your_token_here"
  207. }
  208. }
  209. }
  210. }
  211. ```
  212. *Requires `uv` installed: `pip install uv`*
  213. **Option B: Using installed package**
  214. ```json
  215. {
  216. "mcpServers": {
  217. "joplin": {
  218. "command": "joplin-mcp-server",
  219. "env": {
  220. "JOPLIN_TOKEN": "your_token_here"
  221. }
  222. }
  223. }
  224. }
  225. ```
  226. #### 3. More Client Configuration Examples
  227. For additional client configurations including different transport options (HTTP, SSE, Streamable HTTP), see [client-config.json.example](client-config.json.example).
  228. This file includes configurations for:
  229. - **STDIO transport** (default, most compatible)
  230. - **HTTP transport** (basic HTTP server mode)
  231. - **SSE transport** (recommended for gemini-cli and OpenAI clients)
  232. - **Streamable HTTP transport** (advanced web clients)
  233. - **HTTP-compat transport** (bridges modern `/mcp` JSON-RPC with legacy `/sse`/`/messages` clients)
  234. ### Tool Permission Configuration
  235. Fine-tune which operations the AI can perform by editing your config:
  236. ```json
  237. {
  238. "tools": {
  239. "create_note": true,
  240. "update_note": true,
  241. "delete_note": false,
  242. "create_notebook": true,
  243. "update_notebook": false,
  244. "delete_notebook": false,
  245. "create_tag": true,
  246. "update_tag": false,
  247. "delete_tag": false,
  248. "get_all_notes": false,
  249. "import_from_file": true
  250. }
  251. }
  252. ```
  253. ### Environment Variables
  254. Usable instead of a JSON config file, or alongside one:
  255. ```bash
  256. # Connection settings
  257. export JOPLIN_TOKEN="your_api_token_here"
  258. export JOPLIN_HOST="localhost"
  259. export JOPLIN_PORT="41184"
  260. export JOPLIN_TIMEOUT="30"
  261. ```
  262. Environment variables override the config file key by key, so the `env`
  263. block in your MCP client's configuration wins over whatever file the
  264. server discovers. A variable only takes part when it is actually set, so
  265. setting one leaves the rest of your file alone. Full order: direct
  266. parameters > environment > config file > defaults.
  267. #### Per-Tool Env Vars
  268. Every tool can be toggled individually via `JOPLIN_TOOL_<NAME>=true|false`. These take precedence over config file settings.
  269. | Env var | Default |
  270. |---------|---------|
  271. | `JOPLIN_TOOL_FIND_NOTES` | `true` |
  272. | `JOPLIN_TOOL_FIND_NOTES_WITH_TAG` | `true` |
  273. | `JOPLIN_TOOL_FIND_NOTES_IN_NOTEBOOK` | `true` |
  274. | `JOPLIN_TOOL_FIND_IN_NOTE` | `true` |
  275. | `JOPLIN_TOOL_GET_ALL_NOTES` | `false` |
  276. | `JOPLIN_TOOL_GET_NOTE` | `true` |
  277. | `JOPLIN_TOOL_GET_LINKS` | `true` |
  278. | `JOPLIN_TOOL_CREATE_NOTE` | `true` |
  279. | `JOPLIN_TOOL_UPDATE_NOTE` | `true` |
  280. | `JOPLIN_TOOL_EDIT_NOTE` | `true` |
  281. | `JOPLIN_TOOL_DELETE_NOTE` | `false` |
  282. | `JOPLIN_TOOL_LIST_NOTEBOOKS` | `true` |
  283. | `JOPLIN_TOOL_CREATE_NOTEBOOK` | `true` |
  284. | `JOPLIN_TOOL_UPDATE_NOTEBOOK` | `false` |
  285. | `JOPLIN_TOOL_DELETE_NOTEBOOK` | `false` |
  286. | `JOPLIN_TOOL_LIST_TAGS` | `true` |
  287. | `JOPLIN_TOOL_CREATE_TAG` | `true` |
  288. | `JOPLIN_TOOL_UPDATE_TAG` | `false` |
  289. | `JOPLIN_TOOL_DELETE_TAG` | `false` |
  290. | `JOPLIN_TOOL_GET_TAGS_BY_NOTE` | `true` |
  291. | `JOPLIN_TOOL_TAG_NOTE` | `true` |
  292. | `JOPLIN_TOOL_UNTAG_NOTE` | `true` |
  293. | `JOPLIN_TOOL_PING_JOPLIN` | `true` |
  294. | `JOPLIN_TOOL_RESTORE_FROM_TRASH` | `true` |
  295. | `JOPLIN_TOOL_IMPORT_FROM_FILE` | `false` |
  296. #### Notebook Allowlist Env Var
  297. | Env var | Default | Description |
  298. |---------|---------|-------------|
  299. | `JOPLIN_NOTEBOOK_ALLOWLIST` | *(not set)* | Comma-separated list of notebook patterns (e.g., `Work,Projects/*,!Projects/Secret`). Not set means no restriction; set but empty denies every notebook |
  300. ### HTTP Transport Support
  301. The server supports both STDIO and HTTP transports:
  302. ```bash
  303. # STDIO (default)
  304. joplin-mcp-server --config ~/.joplin-mcp.json
  305. # HTTP transport (development, from repo)
  306. PYTHONPATH=src python -m joplin_mcp.server --transport http --port 8000 --config ./joplin-mcp.json
  307. # Opt-in HTTP compatibility bundle (modern + legacy SSE endpoints)
  308. PYTHONPATH=src python -m joplin_mcp.server --transport http-compat --port 8000 --config ./joplin-mcp.json
  309. # or keep --transport http and export MCP_HTTP_COMPAT=1/true to toggle the same behavior.
  310. ```
  311. #### HTTP client config
  312. Note: Claude Desktop currently uses STDIO transport and does not consume HTTP/SSE configs directly. The following example applies to clients that support network transports.
  313. ```json
  314. {
  315. "mcpServers": {
  316. "joplin": {
  317. "transport": "http",
  318. "url": "http://localhost:8000/mcp"
  319. }
  320. }
  321. }
  322. ```
  323. ### Configuration Reference
  324. #### Basic Settings
  325. | Option | Default | Description |
  326. |--------|---------|-------------|
  327. | `token` | *required* | Joplin API authentication token |
  328. | `host` | `localhost` | Joplin server hostname |
  329. | `port` | `41184` | Joplin Web Clipper port |
  330. | `timeout` | `30` | Request timeout in seconds |
  331. | `verify_ssl` | `false` | SSL certificate verification |
  332. #### Tool Permissions
  333. | Option | Default | Description |
  334. |--------|---------|-------------|
  335. | `tools.create_note` | `true` | Allow creating new notes |
  336. | `tools.update_note` | `true` | Allow modifying existing notes |
  337. | `tools.edit_note` | `true` | Allow precision edits (find/replace, append, prepend) |
  338. | `tools.delete_note` | `false` | Allow deleting notes *(disabled by default — destructive)* |
  339. | `tools.create_notebook` | `true` | Allow creating new notebooks |
  340. | `tools.update_notebook` | `false` | Allow modifying notebook titles and emoji icons |
  341. | `tools.delete_notebook` | `false` | Allow deleting notebooks *(disabled by default — destructive)* |
  342. | `tools.create_tag` | `true` | Allow creating new tags |
  343. | `tools.update_tag` | `false` | Allow modifying tag titles |
  344. | `tools.delete_tag` | `false` | Allow deleting tags *(disabled by default — destructive)* |
  345. | `tools.tag_note` | `true` | Allow adding tags to notes |
  346. | `tools.untag_note` | `true` | Allow removing tags from notes |
  347. | `tools.restore_from_trash` | `true` | Allow restoring soft-deleted notes or notebooks |
  348. | `tools.find_notes` | `true` | Allow text search across notes (with task filtering) |
  349. | `tools.find_notes_with_tag` | `true` | Allow finding notes by tag (with task filtering) |
  350. | `tools.find_notes_in_notebook` | `true` | Allow finding notes by notebook (with task filtering) |
  351. | `tools.find_in_note` | `true` | Allow regex search within a single note |
  352. | `tools.get_all_notes` | `false` | Allow getting all notes (disabled by default - can fill context window) |
  353. | `tools.get_note` | `true` | Allow getting specific notes |
  354. | `tools.get_note_resources` | `true` | Allow reading a note's resources and their OCR text |
  355. | `tools.get_links` | `true` | Allow extracting links to other notes |
  356. | `tools.list_notebooks` | `true` | Allow listing all notebooks |
  357. | `tools.list_tags` | `true` | Allow listing all tags |
  358. | `tools.get_tags_by_note` | `true` | Allow getting tags for specific notes |
  359. | `tools.ping_joplin` | `true` | Allow testing server connectivity |
  360. | `tools.import_from_file` | `false` | Allow importing files/directories (MD, HTML, CSV, TXT, JEX) |
  361. #### Notebook Allowlist
  362. | Option | Default | Description |
  363. |--------|---------|-------------|
  364. | `notebook_allowlist` | `null` | List of notebook patterns to allow access to. `null` = no restriction. Supports gitignore-style patterns: exact names, `*` wildcards, `**` recursive, `!` negation |
  365. #### Content Exposure (Privacy Settings)
  366. | Option | Default | Description |
  367. |--------|---------|-------------|
  368. | `content_exposure.search_results` | `"preview"` | Content visibility in all search and listing results: `"none"`, `"preview"`, `"full"` |
  369. | `content_exposure.individual_notes` | `"full"` | Content visibility for individual notes: `"none"`, `"preview"`, `"full"` |
  370. | `content_exposure.max_preview_length` | `300` | Maximum length of content previews (characters) |
  371. | `content_exposure.smart_toc_threshold` | `2000` | Notes longer than this show a table of contents instead of the full body |
  372. | `content_exposure.enable_smart_toc` | `true` | Turn the table-of-contents fallback off to always return full note bodies |
  373. | `content_exposure.output_hints` | `false` | Emit worked follow-up calls (`NEXT_STEPS`, `NEXT_PAGE`) alongside results. Useful for smaller models, repetition for capable ones |
  374. Lowering `max_preview_length` and `smart_toc_threshold`, or setting
  375. `search_results` to `"none"`, is the main way to cut how many tokens a
  376. session spends. `list_notebooks` and `list_tags` return only the fields
  377. an agent acts on; pass `verbose=True` for icons, parent ids and
  378. timestamps. See [docs/content-privacy.md](docs/content-privacy.md).
  379. ## Docker
  380. Run the MCP server in a container. Default transport is HTTP for broad compatibility; switch via environment variables.
  381. ### Build
  382. ```bash
  383. docker build -t joplin-mcp .
  384. ```
  385. ### Run (HTTP default)
  386. ```bash
  387. docker run --rm \
  388. -p 8000:8000 \
  389. -e JOPLIN_TOKEN=your_api_token \
  390. joplin-mcp
  391. ```
  392. ### With mounted config
  393. ```bash
  394. docker run --rm \
  395. -p 8000:8000 \
  396. -v $PWD/joplin-mcp.json:/config/joplin-mcp.json:ro \
  397. joplin-mcp
  398. ```
  399. ### Choose transport
  400. - SSE (streaming): `-e MCP_TRANSPORT=sse`
  401. - Streamable HTTP: `-e MCP_TRANSPORT=streamable-http`
  402. - STDIO (no port): `-e MCP_TRANSPORT=stdio`
  403. Example (SSE):
  404. ```bash
  405. docker run --rm \
  406. -p 8000:8000 \
  407. -e JOPLIN_TOKEN=your_api_token \
  408. -e MCP_TRANSPORT=sse \
  409. joplin-mcp
  410. ```
  411. The container listens on `0.0.0.0:8000` by default. If exposing publicly, place behind a reverse proxy and terminate TLS there. For SSE, ensure proxy keep-alives and buffering are configured appropriately.
  412. ## Project Structure
  413. - **`src/joplin_mcp/`** - Main package directory
  414. - `fastmcp_server.py` - Server implementation with 26 tools and Pydantic validation types
  415. - `config.py` - Configuration management (including notebook allowlist)
  416. - `notebook_utils.py` - Notebook path resolution, allowlist matching, and caching
  417. - `server.py` - Server entrypoint (module and CLI)
  418. - `tools/` - Tool implementations (notes, notebooks, tags)
  419. - `ui_integration.py` - UI integration utilities
  420. - **`docs/`** - Documentation (troubleshooting, privacy controls, enhancement proposals)
  421. - **`tests/`** - Unit test suite
  422. - **`tests/e2e/`** - End-to-end tests against a real Joplin Desktop (3.x) via the Web Clipper API; see "Running Tests"
  423. ## Testing
  424. Test your connection:
  425. ```bash
  426. # For pip install
  427. joplin-mcp-server --config ~/.joplin-mcp.json
  428. # For development (from repo)
  429. PYTHONPATH=src python -m joplin_mcp.server --config ./joplin-mcp.json
  430. ```
  431. You should see:
  432. ```
  433. Starting Joplin FastMCP Server...
  434. Successfully connected to Joplin!
  435. Found X notebooks, Y notes, Z tags
  436. FastMCP server starting...
  437. Available tools: 26 tools ready
  438. ```
  439. ### Running Tests
  440. ```bash
  441. # Unit tests (no Joplin instance required)
  442. pytest tests/ --ignore=tests/e2e
  443. # E2E tests (requires a running Joplin instance)
  444. JOPLIN_TOKEN=your_api_token \
  445. JOPLIN_HOST=localhost \
  446. JOPLIN_PORT=41184 \
  447. pytest tests/e2e/ -v -m e2e --override-ini="addopts="
  448. ```
  449. The E2E suite talks to a real Joplin Desktop via the Web Clipper API and exercises every tool including notebook allowlist enforcement. If `JOPLIN_HOST:JOPLIN_PORT` is unreachable the suite skips itself, so it's safe to run alongside the unit tests. Requires Joplin 3.x (the trash schema introduced in 3.0 — earlier versions fail with `no such column: deleted_time`).
  450. ## Complete Tool Reference
  451. | Tool | Permission | Description |
  452. |------|------------|-------------|
  453. | **Finding Notes** | | |
  454. | `find_notes` | Read | Full-text search across all notes (supports task filtering; `trash=True` with `query="*"` lists trashed notes) |
  455. | `find_notes_with_tag` | Read | Find notes with specific tag (supports task filtering) |
  456. | `find_notes_in_notebook` | Read | Find notes in specific notebook (supports task filtering) |
  457. | `get_all_notes` | Read | Get all notes, most recent first *(disabled by default)* |
  458. | `get_note` | Read | Get specific note by ID |
  459. | `find_in_note` | Read | Regex search within a single note (paginated matches & context, multiline anchors on by default) |
  460. | `get_links` | Read | Extract links to other notes from a note |
  461. | `get_note_resources` | Read | List a note's resources (images, PDFs, attachments) and read their OCR text |
  462. | **Managing Notes** | | |
  463. | `create_note` | Write | Create new notes |
  464. | `update_note` | Update | Modify existing notes (incl. moving between notebooks) |
  465. | `edit_note` | Update | Precision edit note content (find/replace, append, prepend) |
  466. | `delete_note` | Delete | Remove notes |
  467. | **Managing Notebooks** | | |
  468. | `list_notebooks` | Read | Browse all notebooks |
  469. | `create_notebook` | Write | Create new notebooks under an optional parent (by name or path), optionally with an emoji icon |
  470. | `update_notebook` | Update | Rename, change emoji icon, or move a notebook under another parent (or to top-level with `parent_name="/"`) |
  471. | `delete_notebook` | Delete | Remove notebooks |
  472. | **Managing Tags** | | |
  473. | `list_tags` | Read | View all available tags |
  474. | `create_tag` | Write | Create new tags |
  475. | `update_tag` | Update | Modify tag titles |
  476. | `delete_tag` | Delete | Remove tags |
  477. | `get_tags_by_note` | Read | List tags on specific note |
  478. | **Tag-Note Relationships** | | |
  479. | `tag_note` | Update | Add one or more tags to one or more notes (accepts lists) |
  480. | `untag_note` | Update | Remove one or more tags from one or more notes (accepts lists) |
  481. | **Trash Management** | | |
  482. | `restore_from_trash` | Update | Restore a soft-deleted note or notebook (pass `item_type='note'` or `'notebook'`) |
  483. | **Import Tools** | | |
  484. | `import_from_file` | Write | Import files/directories (MD, HTML, CSV, TXT, JEX) |
  485. | **System Tools** | | |
  486. | `ping_joplin` | Read | Test connectivity |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.