Joplin

This MCP Server for Joplin lets you access and manage your notes through the Model Context Protocol. It enables searching, reading, creating, updating, and deleting notes, plus importing Markdown and integrating with AI assistants like Claude.

How to use

You interact with the Joplin MCP Server through an MCP client or AI assistant that supports MCP. Start the server in development mode to test tools locally, then use a client to search notes, read specific notes, create new notes, update existing ones, or delete notes. You can also import markdown files as notes and enable AI integrations to query and modify your Joplin data.

How to install

Prerequisites include Python 3.10 or higher and Joplin Desktop with Web Clipper Service enabled. You also need the uv tool for Python package management.

Clone the project, create and activate a virtual environment, and install dependencies.

# 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
uv pip install -e .

Configuration

Set up your Joplin API token and MCP server configuration to connect the MCP server with Claude Desktop or other MCP clients.

Create a .env file in the project directory containing your Joplin Web Clipper API token.

JOPLIN_TOKEN=your_api_token_here

Configure Claude Desktop to run the MCP server. The configuration below is an example that shows how to start the MCP server using uv and point to your project path.

{
  "mcpServers": {
    "joplin": {
      "command": "/PATH/TO/UV/uv",
      "args": [
        "--directory",
        "/PATH/TO/YOUR/PROJECT/joplin_mcp",
        "run",
        "src/mcp/joplin_mcp.py"
      ]
    }
  }
}

Development and testing

To start the server in debug mode and test the MCP tools locally, enable verbose logging and run the development command. This will expose an Inspector UI at the given localhost port for interactive testing.

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

Notes and tips

The Joplin MCP Server exposes a set of tools to manage notes. Make sure your Joplin Web Clipper is running and the token is valid. Keep the environment secure since the token grants access to your notes.

Security considerations

Only expose the MCP endpoint to trusted clients. Do not share your JOPLIN_TOKEN or MCP server credentials publicly. Use environment isolation and secure the host where you run the server.

Available tools

search_notes

Search for notes in Joplin using a query string and optional limit for results.

get_note

Retrieve a specific note by its ID.

create_note

Create a new note with a title, optional body, optional parent and optional todo flag.

update_note

Update an existing note with new title, body, parent, or todo status.

delete_note

Delete a note by ID with an option for permanent deletion.

import_markdown

Import a Markdown file as a new note.