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.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/dweigend--joplin-mcp-server)HTML
<a href="/listings/dweigend--joplin-mcp-server"><img src="/api/listings/dweigend--joplin-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
- Python 3.10 or higher - [Joplin Desktop](https://joplinapp.org/) with Web Clipper Service enabled - [uv](https://github.com/astral-sh/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 .
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 173 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 📝 Joplin MCP Server
- A Model Context Protocol (MCP) Server for [Joplin](https://joplinapp.org/) that enables note access through the [Model Context Protocol](https://modelcontextprotocol.io). 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](https://joplinapp.org/) with Web Clipper Service enabled
- - [uv](https://github.com/astral-sh/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
- JOPLIN_TOKEN=your_api_token_here
- ```
- ### 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**
- ```json
- {
- "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/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/joplin_mcp` 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
- ### search_notes
- Search for notes in Joplin.
- **Parameters:**
- - `query` (string): Search query
- - `limit` (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
- ### list_notebooks
- List all available notebooks as a tree.
- **Parameters:**
- - None
- ### create_notebook
- Create a new notebook.
- **Parameters:**
- - `title` (string): Notebook title
- - `parent_id` (string, optional): Parent notebook ID
- - `parent_notebook_name` (string, optional): Parent notebook title or full path
- ### create_note
- Create a new note.
- **Parameters:**
- - `title` (string): Note title
- - `body` (string, optional): Note content in Markdown
- - `parent_id` (string, optional): ID of parent folder
- - `notebook_name` (string, optional): Notebook title or full path such as `Work/Projects`
- - `is_todo` (boolean, optional): Whether this is a todo item
- ### update_note
- Update an existing note.
- **Parameters:**
- - `note_id` (string): ID of note to update
- - `title` (string, optional): New title
- - `body` (string, optional): New content
- - `parent_id` (string, optional): New parent folder ID
- - `notebook_name` (string, optional): New notebook title or full path such as `Work/Projects`
- - `is_todo` (boolean, optional): New todo status
- ### delete_note
- Delete a note.
- **Parameters:**
- - `note_id` (string): ID of note to delete
- - `permanent` (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
- - `parent_id` (string, optional): ID of parent folder
- - `notebook_name` (string, optional): Notebook title or full path such as `Work/Projects`
- ## 🧪 Development
- ### Debug Mode
- To start the server in debug mode:
- ```bash
- 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](LICENSE) - Copyright (c) 2025 David Weigend
- ## 👤 Author
- **David Weigend**
- * Website: [weigend.studio](https://weigend.studio)
- * GitHub: [@dweigend](https://github.com/dweigend)
- ## 🤝 Contributing
- Contributions, issues and feature requests are welcome!
- Visit the [issues page](https://github.com/dweigend/joplin-mcp/issues).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.