Joplin

You run a Joplin MCP Server that exposes note access through the Model Context Protocol, enabling you to search, read, create, update, and delete notes from AI assistants and other MCP clients with a simple, local API surface.

How to use

Use an MCP client to interact with your Joplin MCP Server. You can search for notes, read individual notes, create new notes, update existing ones, delete notes, and import Markdown files as new notes. The server is designed to work with AI assistants that support MCP, making note access seamless and programmable.

How to install

Prerequisites you need before installing: Python 3.10 or higher, Joplin Desktop with Web Clipper Service enabled, and uv as the Python package manager.

Clone the project repository to your machine and navigate into it.

Create and activate a virtual environment using uv.

Install dependencies directly from the project in editable mode.

# 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 and notes

Set up the Joplin Web Clipper API token to authorize the MCP server to access Joplin notes.

JOPLIN_TOKEN=your_api_token_here

Claude Desktop can connect to this MCP server. Use the following MCP server configuration to run the local MCP process with uv.

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

Security and runtime notes

Keep your JOPLIN_TOKEN secure and do not share it publicly. Store it in a environment file or secret manager in production deployments.

If you plan to develop locally, you can enable debug logging to troubleshoot MCP interactions during development.

Available tools

search_notes

Search Joplin notes by a query string and return a list of matching notes up to a specified limit.

get_note

Retrieve the content of a single note by its ID, including metadata like title and body.

create_note

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

update_note

Update an existing note's title, body, parent folder, 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 in Joplin by providing the file path.