joplin

This MCP server exposes a set of tools to interact with Joplin notes via the Model Context Protocol. Once the server is running, you can use the available tools to search, read, create, update, delete, and import markdown notes into Joplin. The tools include search_notes for full-text searches across all notes, get_note to fetch a specific note by ID, create_note and update_note to manage content, delete_note to remove notes (with an option for permanent deletion), and import_markdown to bring in Markdown files as new notes. The server is designed to integrate with AI assistants (like Claude) through MCP, enabling natural-language prompts to drive note management in your Joplin workspace.

Prerequisites:

• Python 3.10 or higher
• Joplin Desktop with Web Clipper Service enabled
• uv (Python package manager)
• Git

Installation steps:

1. Clone the repository

git clone https://github.com/dweigend/joplin-mcp.git
cd joplin-mcp

2. Create and activate a virtual environment using uv

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies in editable mode

uv pip install -e .

4. Ensure you have a JOPLIN_TOKEN from Joplin Web Clipper settings and create an environment file or export the variable

export JOPLIN_TOKEN=your_api_token_here

5. Configure your MCP server (see the configuration example in the repo) and run in debug mode if needed

MCP_LOG_LEVEL=debug mcp dev src/mcp/joplin_mcp.py

6. Access the MCP Inspector at http://localhost:5173 to test the tools.

Notes and tips:

• Ensure Joplin Web Clipper Service is enabled and the API token is correctly set in Joplin and in your environment.
• The Claude Desktop setup example requires the full path to uv; supply the absolute path to your uv binary when configuring the MCP server for Claude.
• If you experience authentication issues, re-check the Joplin token and ensure the token has permission to access Web Clipper.
• The available tools (search_notes, get_note, create_note, update_note, delete_note, import_markdown) map to common note operations; provide required parameters as described in the README when invoking these tools.
• For production deployments, consider setting MCP_LOG_LEVEL to info or warning and running behind a reverse proxy if exposing the MCP Inspector publicly.