📝 Joplin MCP Server
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
- 📖 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
```bash
uv pip install -e .
⚙️ Configuration
Joplin API Token
- Open Joplin Desktop
- Go to Tools -> Options -> Web Clipper
- Enable the Web Clipper Service
- Copy the API Token
Create a .env file in the project directory:
JOPLIN_TOKEN=your_api_token_here
Claude Desktop Setup
-
Install Claude Desktop
- Download Claude Desktop
- Ensure you have the latest version (Menu: Claude -> Check for Updates...)
-
Configure MCP Server
{ "mcpServers": { "joplin": { "command": "/PATH/TO/UV/uv", "args": [ "--directory", "/PATH/TO/YOUR/PROJECT/joplin_mcp", "run", "src/mcp/joplin_mcp.py" ] } } }
- Replace
/PATH/TO/UV/uvwith the absolute path to your uv installation- Find the path with:
which uv - Example macOS:
/Users/username/.local/bin/uv - Example Windows:
C:\Users\username\AppData\Local\Microsoft\WindowsApps\uv.exe
- Find the path with:
- Replace
/PATH/TO/YOUR/PROJECT/joplin_mcpwith the absolute path to your project
Important: Claude Desktop needs the full path to
uvas it cannot access shell environment variables. - Replace
🛠️ Available Tools
search_notes
Search for notes in Joplin.
Parameters:
query(string): Search querylimit(int, optional): Maximum number of results (default: 100)
get_note
Retrieve a specific note by its ID.
Parameters:
note_id(string): ID of the note
create_note
Create a new note.
Parameters:
title(string): Note titlebody(string, optional): Note content in Markdownparent_id(string, optional): ID of parent folderis_todo(boolean, optional): Whether this is a todo item
update_note
Update an existing note.
Parameters:
note_id(string): ID of note to updatetitle(string, optional): New titlebody(string, optional): New contentparent_id(string, optional): New parent folder IDis_todo(boolean, optional): New todo status
delete_note
Delete a note.
Parameters:
note_id(string): ID of note to deletepermanent(boolean, optional): If true, permanently delete the note
import_markdown
Import a markdown file as a new note.
Parameters:
file_path(string): Path to the markdown file
🧪 Development
Debug Mode
To start the server in debug mode:
MCP_LOG_LEVEL=debug mcp dev src/mcp/joplin_mcp.py
This starts the MCP Inspector at http://localhost:5173 where you can test the tools.
📄 License
MIT License - Copyright (c) 2025 David Weigend
👤 Author
David Weigend
- Website: weigend.studio
- GitHub: @dweigend
🤝 Contributing
Contributions, issues and feature requests are welcome! Visit the issues page.
Metadata
Release files for iflow-mcp_dweigend-joplin-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_dweigend_joplin_mcp-0.1.0.tar.gz | 46.0 kB | Without provenance | Details for iflow_mcp_dweigend_joplin_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_dweigend_joplin_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_dweigend_joplin_mcp-0.1.0-py3-none-any.whl |
Total release size: 61.3 kB
Release files / iflow_mcp_dweigend_joplin_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_dweigend_joplin_mcp-0.1.0.tar.gz |
|---|---|
| Size | 46.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c059fb9fb607ed49222971fc56957f118aec501b7697a70db7439c4b15f70f34
|
|
BLAKE2b-256 checksum How to use checksums |
336f43aedfdef5f4b07ba3dc6685f39b7b75ecb7faf459c74ed6c853dca985c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_dweigend_joplin_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_dweigend_joplin_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 15.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cc2f4e0c9964b76a142530f5fc50065c03f5afa2ed11ce7c25a1fcd4e68ccf4d
|
|
BLAKE2b-256 checksum How to use checksums |
49b17b241a59985aac38b4b89ff50fdc5689211a1e1a4af616b479580c691e56
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_dweigend-joplin-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.