JoplinSAFE
A Model Context Protocol (MCP) Server for https://joplinapp.org/ that enables note access through the https://modelcontextprotocol.io. Perfect for integration with AI assistants like Claude.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
A Model Context Protocol (MCP) Server for Joplin that enables note access through the Model Context Protocol. Perfect for integration with AI assistants like Claude.
✨ Features
- 🔍 Search Notes: Full-text search across all notes
- 📚 List Notebooks: Browse available notebooks and sub-notebooks
- 🗂️ Create Notebooks: Create notebooks and nested sub-notebooks
- 📖 Read Notes: Retrieve individual notes
- ✏️ Edit Notes: Create new notes and update existing ones
- 🗑️ Delete Notes: Move notes to trash or delete permanently
- 📥 Markdown Import: Import markdown files as notes
- 🤖 AI Integration: Seamless integration with Claude and other MCP-capable AI assistants
🚀 Installation
Prerequisites
- Python 3.10 or higher
- Joplin Desktop with Web Clipper Service enabled
- uv (Python package manager)
# Clone repository git clone https://github.com/dweigend/joplin-mcp.git cd joplin-mcp # Create and activate virtual environment uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies
uv pip install -e .
## ⚙️ Configuration ### Joplin API Token 1. Open Joplin Desktop 2. Go to Tools -> Options -> Web Clipper 3. Enable the Web Clipper Service 4. Copy the API Token Create a `.env` file in the project directory:
JOPLINTOKEN=yourapitokenhere
### Claude Desktop Setup 1. **Install Claude Desktop** - Download [Claude Desktop](https://claude.ai/download) - Ensure you have the latest version (Menu: Claude -> Check for Updates...) 2. **Configure MCP Server**
{ "mcpServers": { "joplin": { "command": "/PATH/TO/UV/uv", "args": [ "--directory", "/PATH/TO/YOUR/PROJECT/joplinmcp", "run", "src/mcp/joplinmcp.py" ] } }
694f137e7ce9OBSERVED · 2026-10-07Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control.
claude mcp add joplin-mcp -- uvx joplin-mcp
{
"mcpServers": {
"joplin-mcp": {
"command": "uvx",
"args": [
"joplin-mcp"
]
}
}
}Exposed tools (11)
5 read · 5 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
build_semantic_index | write | Build or update the local semantic search index. |
create_note | write | Create a new note in Joplin. |
create_notebook | write | Create a new Joplin notebook. |
delete_note | destructive | Delete a note from Joplin. |
find_linked_notes | read | Find notes connected to a note by Joplin |
find_similar_notes | read | Find notes whose content resembles a given note. |
get_note | read | Get a specific note by ID. |
import_markdown | write | Import a markdown file as a new note. |
list_notebooks | read | List available Joplin notebooks. |
search_notes | read | Search for notes in Joplin by keyword, meaning, or both. |
update_note | write | Update an existing note in Joplin. |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- none-observed
- Shell
- none-observed
- Dependencies
- pinned
- Secrets in source
- none-found
Findings (2)
delete_note
**Important**: Claude Desktop needs the full path to `uv` as it cannot access shell environment variables.
Gates applied: no_behavioural_pass.
694f137e7ce9full audit observations/trust-audit/mcp-server/dweigend__joplin.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | 694f137e7ce9 | SAFE | B | 89 | first audit |
Questions
What is the Joplin MCP server?
A Model Context Protocol (MCP) Server for https://joplinapp.org/ that enables note access through the https://modelcontextprotocol.io. Perfect for integration with AI assistants like Claude.
What tools does Joplin expose?
11 in total: 5 read-only, 5 that write, and 1 that can delete or overwrite (delete_note). Every one is listed on this page with its risk.
Is Joplin safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Joplin need?
No credential environment variables were found in its source, so it appears to need none.
How does Joplin run?
It speaks stdio, so it runs as a local process your client starts. It is published on PyPI as joplin-mcp.
How current is this page?
The grade is for one exact copy of the source (694f137e7ce9), read on 2026-10-07. The repository is watched and re-audited when it changes.