Best for
- Users who want to manage a personal Joplin knowledge base through AI.
- MCP client users who need note, notebook, and tag search and organization.
- Users who need to restrict AI access by notebook path.
J
55FMRS · C
An unofficial Joplin MCP server covering notes, notebooks, tags, trash recovery, and file imports, with configurable tool permissions and notebook allowlists. It depends on Joplin Web Clipper and an authorization token; write, delete, import, and network-exposure settings require careful configuration.
Joplin MCP Server is a FastMCP-based server that uses the Joplin Web Clipper API and the Python library joppy to let MCP-compatible AI assistants access and manage Joplin notes, notebooks, and tags. It supports search, reading, creation, editing, organization, restoration, and file imports.
Tools
find_notes
Search notes, with task filtering and trash queries.
find_notes_with_tag
Find notes by tag, with task filtering.
find_notes_in_notebook
Find notes in a notebook, with task filtering.
get_all_notes
Retrieve all notes, most recent first; disabled by default.
get_note
Retrieve a specific note by ID.
find_in_note
Run a regular-expression search within one note with paginated matches and context.
get_links
Extract links to other notes.
get_note_resources
List note resources and read OCR text from images and PDFs.
create_note
Create notes.
update_note
Modify notes, including moving them between notebooks.
edit_note
Precisely edit note content by find/replace, append, or prepend operations.
delete_note
Delete notes.
list_notebooks
List accessible notebooks.
create_notebook
Create a notebook with an optional parent notebook and emoji icon.
update_notebook
Rename, change the icon of, or move a notebook.
delete_notebook
Delete notebooks.
list_tags
List tags.
create_tag
Create tags.
update_tag
Modify tag titles.
delete_tag
Delete tags.
get_tags_by_note
List tags assigned to a note.
tag_note
Add one or more tags to one or more notes.
untag_note
Remove one or more tags from one or more notes.
restore_from_trash
Restore a soft-deleted note or notebook.
import_from_file
Import Markdown, HTML, CSV, TXT, JEX files, or directories.
ping_joplin
Test connectivity to Joplin.
Setup
In Joplin Desktop, open Tools → Options → Web Clipper, enable the Web Clipper service, and copy its authorization token. After installing uv, use the provided Claude Desktop configuration or run uvx --from joplin-mcp joplin-mcp-server. You can also install joplin-mcp with pip. JOPLIN_TOKEN is required; JOPLIN_URL can optionally override the default http://localhost:41184. Restart the client after configuration.
claude_desktop_config.json
{"mcpServers":{"joplin":{"command":"uvx","args":["--from","joplin-mcp","joplin-mcp-server"],"env":{"JOPLIN_TOKEN":"your_token_here"}}}}
Fit and risk
Not for
- Users who do not use Joplin or cannot enable Web Clipper.
- Users who cannot provide a Joplin API authorization token.
- Read-only scenarios where write, update, or import permissions are not desired.
Required permissions
- Requires a running Joplin Web Clipper authorization token supplied through JOPLIN_TOKEN.
- Read permissions cover searching, viewing notebooks and tags, and connectivity checks.
- Write, update, delete, and import operations can be controlled individually through configuration or environment variables.
- Delete operations, retrieving all notes, and file imports are disabled by default.
- notebook_allowlist can restrict read and write access by notebook path.
Risks and side effects
- After enabling delete, update, or import tools, an AI assistant can modify or delete Joplin content; delete operations are disabled by default.
- Without a notebook allowlist, all notebooks are accessible by default.
- Search results and individual notes can expose content; content_exposure settings control previews and full bodies.
- When exposing HTTP or SSE publicly, operators must configure a reverse proxy and TLS; the documentation recommends a reverse proxy for public exposure.
- The token is a secret credential and should not be exposed or placed in untrusted configuration.
Troubleshooting
- Confirm that Joplin Desktop is running and Web Clipper is enabled.
- Check that JOPLIN_TOKEN belongs to the current Joplin instance.
- The default endpoint is http://localhost:41184; set JOPLIN_URL or the corresponding host and port settings if it differs.
- If using uvx, confirm that uv is installed; if using pip, confirm that joplin-mcp is installed.
- Restart Claude Desktop, Jan AI, or the relevant client after changing its configuration.
- End-to-end tests require a running Joplin 3.x instance; tests skip themselves when the connection is unreachable.
Use cases
Search and read Joplin notes.
Create meeting notes and other new notes.
Organize notebooks and tags.
Restore notes or notebooks from trash.
Import Markdown, HTML, CSV, TXT, or JEX content.
Supported clients
Claude DesktopFull support
Jan AIFull support
OllMCPFull support