Joplin MCP Server
A FastMCP-based Model Context Protocol (MCP) server for Joplin note-taking application via its Python API joppy, enabling AI assistants to interact with your Joplin notes, notebooks, and tags through a standardized interface.
Potencialize seu agente
O comando do próprio publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
uvx joplin-mcp==0.10.0O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
JOPLIN_TOKEN=<secret> JOPLIN_URL=<value> claude mcp add alondmnt-joplin-mcp -- uvx joplin-mcp==0.10.0Execute em um terminal.
{ "mcpServers": { "alondmnt-joplin-mcp": { "command": "uvx", "args": [ "joplin-mcp==0.10.0" ], "env": { "JOPLIN_TOKEN": "<secret>", "JOPLIN_URL": "<value>" } } }}claude_desktop_config.json
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
A FastMCP-based Model Context Protocol (MCP) server for Joplin note-taking application via its Python API joppy, enabling AI assistants to interact with your Joplin notes, notebooks, and tags through a standardized interface.
MCP server for the Joplin note taking app
This MCP server provides 26 optimized tools for comprehensive Joplin integration:
find_notes (supports trash=True for trashed notes), find_notes_with_tag, find_notes_in_notebook, get_all_notesget_note, get_note_resources (read OCR text from attached images/PDFs), get_links, create_note, update_note, edit_note, delete_notelist_notebooks, create_notebook, update_notebook, delete_notebooklist_tags, create_tag, update_tag, delete_tag, get_tags_by_notetag_note, untag_noterestore_from_trash - Restore soft-deleted notes or notebooksimport_from_file - Import Markdown, HTML, CSV, TXT, JEX files and directoriesping_joplinAny MCP-compatible client should work. Below are the ones with documented setup instructions.
Run the automated installer:
# Install and configure everything automatically (pip)
pip install joplin-mcp
joplin-mcp-install
# Or use zero-install with uvx (recommended if you have uv)
uvx --from joplin-mcp joplin-mcp-install
# Optional: pin a specific version/range for stability
uvx --from joplin-mcp==0.4.1 joplin-mcp-install
uvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install
This script will:
After setup, restart Claude Desktop and you're ready to go!
Install the orchestration plugin for smarter tool usage (edit vs update, long-note reading, bulk tagging):
/plugin marketplace add alondmnt/joplin-mcp
/plugin install joplin-mcp
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.
Install Jan AI from https://jan.ai
Add MCP Server in Jan's interface:
joplinuvx --from joplin-mcp joplin-mcp-server (requires uv installed)JOPLIN_TOKEN: your_joplin_api_token_hereStart chatting with access to your Joplin notes!
Automated Setup (Alternative)
# Install and configure Jan AI automatically (if Jan is already installed)
pip install joplin-mcp
joplin-mcp-install
This will detect and configure Jan AI automatically, just like Claude Desktop.
Auto-discovery (if you set up Claude Desktop first)
# Install ollmcp
pip install ollmcp
# Run with auto-discovery (requires existing Claude Desktop config)
ollmcp --auto-discovery --model qwen3:4b
Manual setup (works independently)
# Install ollmcp
pip install ollmcp
# Set environment variable
export JOPLIN_TOKEN="your_joplin_api_token_here"
# Run with uvx (requires uv installed)
ollmcp --server "joplin:uvx --from joplin-mcp joplin-mcp-server" --model qwen3:4b
# Or with an installed package (pip install joplin-mcp)
ollmcp --server "joplin:joplin-mcp-server" --model qwen3:4b
Once configured, you can ask your AI assistant:
find_notes(task=True)The setup script offers 4 permission levels:
Choose the level that matches your comfort and use case.
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.
JSON config (joplin-mcp.json):
{
"token": "your_token",
"notebook_allowlist": ["Work", "Projects/Public"]
}
Environment variable:
export JOPLIN_NOTEBOOK_ALLOWLIST="Work,Projects/Public"
Patterns use gitignore/gitwildmatch semantics:
Negation patterns always win over positive patterns (any negation match on a path or ancestor denies access).
Projects means notes in Projects/Work/Tasks are also accessible.get_note, get_note_resources, find_notes, get_links — notes in blocked notebooks are filtered out or rejected.create_note, update_note, edit_note, delete_note — operations on notes in blocked notebooks are rejected.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.find_notes results are filtered to only include notes in accessible notebooks.tag_note, untag_note, get_tags_by_note enforce access on the note's notebook.Single project focus (notebook name containing a space):
{ "notebook_allowlist": ["Work Projects"] }
Multiple notebooks with exclusion:
{ "notebook_allowlist": ["Projects", "!Projects/Secret", "AI", "Reference"] }
Glob patterns:
{ "notebook_allowlist": ["Projects/*", "!Projects/Private"] }
No allowlist (default) — all notebooks accessible:
{ "notebook_allowlist": null }
At server startup, the allowlist is validated and logged:
For developers or users who want the latest features:
git clone https://github.com/alondmnt/joplin-mcp.git
cd joplin-mcp
python bootstrap.py
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.
If you prefer manual setup or the script doesn't work:
Note on
uvx:uvxruns Python applications without permanently installing them (requiresuv:pip install uv). It can read and write user configuration files (e.g., Claude/Jan configs), souvx --from joplin-mcp joplin-mcp-installworks for setup just like a pip install.
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-installoruvx --from 'joplin-mcp>=0.4,<0.5' joplin-mcp-install.
Create joplin-mcp.json in your project directory:
{
"token": "your_api_token_here",
"host": "localhost",
"port": 41184,
"timeout": 30,
"verify_ssl": false
}
Add to your claude_desktop_config.json:
Option A: Using uvx (Zero-install)
{
"mcpServers": {
"joplin": {
"command": "uvx",
"args": ["--from", "joplin-mcp", "joplin-mcp-server"],
"env": {
"JOPLIN_TOKEN": "your_token_here"
}
}
}
}
Requires uv installed: pip install uv
Option B: Using installed package
{
"mcpServers": {
"joplin": {
"command": "joplin-mcp-server",
"env": {
"JOPLIN_TOKEN": "your_token_here"
}
}
}
}
For additional client configurations including different transport options (HTTP, SSE, Streamable HTTP), see client-config.json.example.
This file includes configurations for:
/mcp JSON-RPC with legacy /sse//messages clients)Fine-tune which operations the AI can perform by editing your config:
{
"tools": {
"create_note": true,
"update_note": true,
"delete_note": false,
"create_notebook": true,
"update_notebook": false,
"delete_notebook": false,
"create_tag": true,
"update_tag": false,
"delete_tag": false,
"get_all_notes": false,
"import_from_file": true
}
}
Usable instead of a JSON config file, or alongside one:
# Connection settings
export JOPLIN_TOKEN="your_api_token_here"
export JOPLIN_HOST="localhost"
export JOPLIN_PORT="41184"
export JOPLIN_TIMEOUT="30"
Environment variables override the config file key by key, so the env
block in your MCP client's configuration wins over whatever file the
server discovers. A variable only takes part when it is actually set, so
setting one leaves the rest of your file alone. Full order: direct
parameters > environment > config file > defaults.
Every tool can be toggled individually via JOPLIN_TOOL_<NAME>=true|false. These take precedence over config file settings.
The server supports both STDIO and HTTP transports:
# STDIO (default)
joplin-mcp-server --config ~/.joplin-mcp.json
# HTTP transport (development, from repo)
PYTHONPATH=src python -m joplin_mcp.server --transport http --port 8000 --config ./joplin-mcp.json
# Opt-in HTTP compatibility bundle (modern + legacy SSE endpoints)
PYTHONPATH=src python -m joplin_mcp.server --transport http-compat --port 8000 --config ./joplin-mcp.json
# or keep --transport http and export MCP_HTTP_COMPAT=1/true to toggle the same behavior.
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.
{
"mcpServers": {
"joplin": {
"transport": "http",
"url": "http://localhost:8000/mcp"
}
}
}
Lowering max_preview_length and smart_toc_threshold, or setting
search_results to "none", is the main way to cut how many tokens a
session spends. list_notebooks and list_tags return only the fields
an agent acts on; pass verbose=True for icons, parent ids and
timestamps. See docs/content-privacy.md.
Run the MCP server in a container. Default transport is HTTP for broad compatibility; switch via environment variables.
docker build -t joplin-mcp .
docker run --rm \
-p 8000:8000 \
-e JOPLIN_TOKEN=your_api_token \
joplin-mcp
docker run --rm \
-p 8000:8000 \
-v $PWD/joplin-mcp.json:/config/joplin-mcp.json:ro \
joplin-mcp
-e MCP_TRANSPORT=sse-e MCP_TRANSPORT=streamable-http-e MCP_TRANSPORT=stdioExample (SSE):
docker run --rm \
-p 8000:8000 \
-e JOPLIN_TOKEN=your_api_token \
-e MCP_TRANSPORT=sse \
joplin-mcp
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.
src/joplin_mcp/ - Main package directory
fastmcp_server.py - Server implementation with 26 tools and Pydantic validation typesconfig.py - Configuration management (including notebook allowlist)notebook_utils.py - Notebook path resolution, allowlist matching, and cachingserver.py - Server entrypoint (module and CLI)tools/ - Tool implementations (notes, notebooks, tags)ui_integration.py - UI integration utilitiesdocs/ - Documentation (troubleshooting, privacy controls, enhancement proposals)tests/ - Unit test suitetests/e2e/ - End-to-end tests against a real Joplin Desktop (3.x) via the Web Clipper API; see "Running Tests"Test your connection:
# For pip install
joplin-mcp-server --config ~/.joplin-mcp.json
# For development (from repo)
PYTHONPATH=src python -m joplin_mcp.server --config ./joplin-mcp.json
You should see:
Starting Joplin FastMCP Server...
Successfully connected to Joplin!
Found X notebooks, Y notes, Z tags
FastMCP server starting...
Available tools: 26 tools ready
# Unit tests (no Joplin instance required)
pytest tests/ --ignore=tests/e2e
# E2E tests (requires a running Joplin instance)
JOPLIN_TOKEN=your_api_token \
JOPLIN_HOST=localhost \
JOPLIN_PORT=41184 \
pytest tests/e2e/ -v -m e2e --override-ini="addopts="
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).
MCP server for the Joplin note taking app
{ "mcpServers": { "alondmnt-joplin-mcp": { "command": "uvx", "args": [ "joplin-mcp==0.10.0" ], "env": { "JOPLIN_TOKEN": "<secret>", "JOPLIN_URL": "<value>" } } }}Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
O publicador lista estas variáveis de ambiente: JOPLIN_TOKEN, JOPLIN_URL.
Joplin roda localmente via stdio.
Última verificação: 2026-11-05. MCP server for the Joplin note taking app