M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
J

Joplin MCP Server

Community
Manage Joplin notes through MCP.
How to install ↓ Compare GitHub source repository ↗
Category
Other #106 of 230
Stars
★ 174 Popular
Transport
stdio (local process) · SSE · Streamable HTTP
Runtime
Python · Docker
Credentials
API key / credential required
License
MIT
Last commit
Tools
26
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.

Strongest · Documentation 14/20 Weakest · Maintenance 8/20

Reliability
9/20
Security and permissions
11/20
Maintenance
8/20
Documentation
14/20
Setup experience
13/20
Why each score
Reliability 9/20
The README describes 26 tools, unit tests, end-to-end tests, and a stdio launch path; however, this review has only README and manifest evidence, with no verifiable CI workflows, test contents, or implementation-level error handling. The manifest declares only stdio while the README also documents several HTTP transports, and JOPLIN_URL is described differently from the README's JOPLIN_HOST/JOPLIN_PORT settings. The happy path is plausible, but initialization, tool-list handshake, and edge-case behavior are not verifiable, so the static cap requires a deduction.
Security and permissions 11/20
JOPLIN_TOKEN is marked secret and the default transport is local stdio. Tool permissions are configurable, destructive delete tools are disabled by default, and the project documents notebook allowlists, content-exposure controls, and access filtering. These support a reasonable baseline for least privilege and data boundaries. Deductions apply because create and update operations are generally enabled unless configured otherwise, restore_from_trash is enabled by default, and mandatory user confirmation is not evidenced; HTTP/Docker examples bind to 0.0.0.0 without documented network authentication or authorization; verify_ssl defaults to false; and individual note content defaults to full exposure. No red-line risk is evidenced, but the controls are not sufficient for a near-perfect score.
Maintenance 8/20
The repository is not archived, declares an MIT license, and provides a 0.9.0 manifest/package version with six open issues, giving some evidence of an active project. Deductions are necessary because the source material provides no commit or release cadence, maintainer response record, dependency-update policy, vulnerability disclosure channel, or clearly documented ownership. Sustained maintenance and security-response capacity therefore cannot be established.
Documentation 14/20
The README covers installation, obtaining the Joplin token, multiple clients, tool categories, permission switches, notebook allowlists, privacy settings, Docker, transports, configuration variables, testing commands, and troubleshooting, making it comparatively thorough. Points are deducted because tool parameters and response limitations are not systematically specified, manifest and README transport/environment-variable descriptions differ, and there is no evidence for dependency maintenance, operating cost, or independently verifiable implementation behavior.
Setup experience 13/20
The project provides pip, uvx, source bootstrap, Claude Desktop, Claude Code, Jan, OllMCP, Docker, and manual configuration examples, with generally clear connection steps. Deductions apply because Joplin Web Clipper must be running and a token must be obtained, some paths depend on uv, client-specific configuration, or local file changes, and the transport choices add complexity while the manifest declares only stdio. With no real CI or execution evidence, the static calibration limits this score to 15 or below.

Static review · not runListed 2026-08-14

Read the FMRS scoring method →

Fit and risk

What it can accessUses the network

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.

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.

Setup

Before you start

Runtime：Python · Docker

JOPLIN_TOKEN requiredsecret Web Clipper authorization token from Joplin Desktop (Tools → Options → Web Clipper); required and secret.
Other optional settings (8)
JOPLIN_URL optional Optional override for the Joplin Web Clipper base URL, default http://localhost:41184.
JOPLIN_HOST optional Optional Joplin server hostname, default localhost.
JOPLIN_PORT optional Optional Joplin Web Clipper port, default 41184.
JOPLIN_TIMEOUT optional Optional request timeout in seconds, default 30.
JOPLIN_NOTEBOOK_ALLOWLIST optional Optional comma-separated gitignore-style notebook patterns restricting which notebooks the AI can access.
JOPLIN_TOOL_DELETE_NOTE optional Optional toggle to enable the delete_note tool; default false.
JOPLIN_TOOL_GET_ALL_NOTES optional Optional toggle to enable the get_all_notes tool; default false.
JOPLIN_TOOL_IMPORT_FROM_FILE optional Optional toggle to enable the import_from_file tool; default false.

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"}}}}

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json
{
  "servers": {
    "joplin": {
      "command": "uvx",
      "args": [
        "--from",
        "joplin-mcp",
        "joplin-mcp-server"
      ],
      "env": {
        "JOPLIN_TOKEN": "your_token_here"
      }
    }
  }
}

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add joplin -e JOPLIN_TOKEN=your_token_here -- uvx --from joplin-mcp joplin-mcp-server

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

After connecting the client, invoke ping_joplin or ask 'List all my notebooks' — a returned notebook list confirms the connection to Joplin works.

Troubleshooting

  1. Confirm that Joplin Desktop is running and Web Clipper is enabled.
  2. Check that JOPLIN_TOKEN belongs to the current Joplin instance.
  3. The default endpoint is http://localhost:41184; set JOPLIN_URL or the corresponding host and port settings if it differs.
  4. If using uvx, confirm that uv is installed; if using pip, confirm that joplin-mcp is installed.
  5. Restart Claude Desktop, Jan AI, or the relevant client after changing its configuration.
  6. End-to-end tests require a running Joplin 3.x instance; tests skip themselves when the connection is unreachable.

Things to try

Once connected, you can ask your AI assistant things like:

  • List all my notebooks
  • Find notes about Python programming
  • Create a meeting note for today's standup
  • Tag my recent AI notes as 'important'

Tools 26

find_notes read-only
Search notes, with task filtering and trash queries.
find_notes_with_tag read-only
Find notes by tag, with task filtering.
find_notes_in_notebook read-only
Find notes in a notebook, with task filtering.
get_all_notes read-only
Retrieve all notes, most recent first; disabled by default.
get_note read-only
Retrieve a specific note by ID.
find_in_note read-only
Run a regular-expression search within one note with paginated matches and context.
get_links read-only
Extract links to other notes.
get_note_resources read-only
List note resources and read OCR text from images and PDFs.
Show 18 more tools
create_note writes
Create notes.
update_note writes
Modify notes, including moving them between notebooks.
edit_note writes
Precisely edit note content by find/replace, append, or prepend operations.
delete_note destructive
Delete notes.
list_notebooks read-only
List accessible notebooks.
create_notebook writes
Create a notebook with an optional parent notebook and emoji icon.
update_notebook writes
Rename, change the icon of, or move a notebook.
delete_notebook destructive
Delete notebooks.
list_tags read-only
List tags.
create_tag writes
Create tags.
update_tag writes
Modify tag titles.
delete_tag destructive
Delete tags.
get_tags_by_note read-only
List tags assigned to a note.
tag_note writes
Add one or more tags to one or more notes.
untag_note writes
Remove one or more tags from one or more notes.
restore_from_trash writes
Restore a soft-deleted note or notebook.
import_from_file writes
Import Markdown, HTML, CSV, TXT, JEX files, or directories.
ping_joplin read-only
Test connectivity to Joplin.

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 Desktop
Jan AI
OllMCP

Listed from the project's documentation, not tested by this site.

Overview

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.

Similar servers

BioMCP 75 · B

One binary. One grammar. Evidence from the biomedical sources you already trust.

★ 659 · Tools 11 Compare with this →
Compare with other MCP servers

Source revision b84c3131e64c Data synced 2026-10-19 Read the FMRS scoring method