Joplin

🚀 Joplin MCP Server

This is a Model Context Protocol (MCP) server implemented for Joplin. It enables note access through this protocol and is highly suitable for integration with AI assistants like Claude.

🚀 Quick Start

The Joplin MCP Server allows you to access notes via the MCP protocol and integrate seamlessly with AI assistants. It provides a range of features for note management and interaction.

✨ Features

• 🔍 Search Notes: Conduct full-text searches across all notes.
• 📖 Read Notes: Retrieve a single note.
• ✏️ Edit Notes: Create new notes and update existing ones.
• 🗑️ Delete Notes: Move notes to the trash or permanently delete them.
• 📥 Markdown Import: Import Markdown files as notes.
• 🤖 AI Integration: Seamlessly integrate with Claude and other MCP - supported AI assistants.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• Joplin Desktop with the Web Clipper service enabled.
• uv (Python package manager).

# Clone the repository
git clone https://github.com/dweigend/joplin-mcp.git
cd joplin-mcp

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

📚 Documentation

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:

JOPLIN_TOKEN=your_api_token_here

Claude Desktop Settings

1. Install Claude Desktop

   • Download Claude Desktop.
   • Ensure you are using the latest version (Menu: Claude -> Check for Updates...).

2. Configure the 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/uv with the absolute path of the uv installation.
     • Use which uv to find the path (e.g., on macOS: /Users/username/.local/bin/uv).
     • Example on Windows: C:\Users\username\AppData\Local\Microsoft\WindowsApps\uv.exe.
   • Replace /PATH/TO/YOUR/PROJECT/joplin_mcp with the absolute path of the project.

   ⚠️ Important Note

   Claude Desktop requires the full path of uv because it cannot access shell environment variables.

Available Tools

• Search Notes: Conduct full - text searches across all notes.
• Read Notes: Retrieve a single note.
• Edit Notes: Create new notes or update existing ones.
• Delete Notes: Move notes to the trash or permanently delete them.
• Markdown Import: Import Markdown files as notes.
• AI Integration: Seamlessly integrate with Claude and other MCP - supported AI assistants.

Development

Debug Mode

To enable debug mode, set the following in the configuration:

DEBUG=True

Logging

The default log level is INFO. To change the log level, set:

LOG_LEVEL=DEBUG  # Available values: DEBUG, INFO, WARNING, ERROR, CRITICAL

📄 License

This project is licensed under the MIT License.

🎤 Author

David Weigend

• Website: weigend.studio
• GitHub: @dweigend

🤝 Contribution

Contributions, issues, and feature requests are welcome! Visit the Issues page.