dweigend/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
📚 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)
bash
# 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
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:
bash
JOPLINTOKEN=yourapitokenhere
### Claude Desktop Setup
1. Install Claude Desktop
Download Claude Desktop
Ensure you have the latest version (Menu: Claude -> Check for Updates...)
2. Configure MCP Server
json
"mcpServers": {
"joplin": {
"command": "/PATH/TO/UV/uv",
"args": [
"--directory",
"/PATH/TO/YOUR/PROJECT/joplinmcp",
"run",
"src/mcp/joplinmcp.py"
Replace /PATH/TO/UV/uv with 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
Replace /PATH/TO/YOUR/PROJECT/joplinmcp with the absolute path to your project
Important: Claude Desktop needs the full path to uv as it cannot access shell environment variables.
## 🛠️ Available Tools
### searchnotes
Search for notes in Joplin.
Parameters:
query (string): Search query
limit (int, optional): Maximum number of results (default: 100)
### getnote
Retrieve a specific note by its ID.
Parameters:
noteid (string): ID of the note
### listnotebooks
List all available notebooks as a tree.
Parameters:
None
### createnotebook
Create a new notebook.
Parameters:
title (string): Notebook title
parentid (string, optional): Parent notebook ID
parentnotebookname (string, optional): Parent notebook title or full path
### createnote
Create a new note.
Parameters:
title (string): Note title
body (string, optional): Note content in Markdown
parentid (string, optional): ID of parent folder
notebookname (string, optional): Notebook title or full path such as Work/Projects
istodo (boolean, optional): Whether this is a todo item
### updatenote
Update an existing note.