home / mcp / joplin mcp server

Joplin MCP Server

Provides an MCP API to access Joplin notes, notebooks, and sync operations via a self-contained server.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jordanburke-joplin-mcp-server": {
      "command": "npx",
      "args": [
        "joplin-mcp-server",
        "--token",
        "your_joplin_token"
      ],
      "env": {
        "LOG_LEVEL": "info",
        "JOPLIN_CLI": "/usr/local/bin/joplin",
        "JOPLIN_HOST": "192.168.1.100",
        "JOPLIN_PORT": "41184",
        "JOPLIN_TOKEN": "your_joplin_token",
        "JOPLIN_PROFILE": "~/.config/joplin-mcp",
        "JOPLIN_SYNC_PATH": "/path/to/sync/dir",
        "JOPLIN_SYNC_TARGET": "filesystem",
        "JOPLIN_SYNC_PASSWORD": "s3cr3t",
        "JOPLIN_SYNC_USERNAME": "[email protected]"
      }
    }
  }
}

You can run a self-contained MCP server for Joplin that exposes your notes via the Model Context Protocol. It bundles the Joplin Terminal CLI, runs without a separate desktop app, and coordinates with your existing Joplin setup to provide a streamlined MCP API for note data and operations.

How to use

You use the server by starting it with your Joplin API token. The server can run in sidecar mode, where it manages its own Joplin Terminal instance, or in external mode by connecting to an already running Joplin instance. Start in sidecar mode to have automatic port negotiation and built-in data handling, then connect your MCP client to the exposed MCP endpoints.

How to install

Prerequisites: you need Node.js installed on your system. You will also use a package runner to invoke the MCP server. The following steps assume you want to run the server in sidecar mode with a token.

# Install and run the MCP server in sidecar mode
npx joplin-mcp-server --token your_joplin_token

Additional configuration and usage notes

You can customize how the server syncs by supplying additional options. The server supports various sync backends, including cloud and filesystem paths. You can also connect to an existing Joplin instance by setting host and port in external mode.

Configuration

Environment variables you can set to configure the MCP server include the following. These are the variables shown as part of the server configuration and are used to control how the server authenticates and connects to Joplin.

Security and notes

Keep your API token secure. Configure only trusted networks and consider using TLS termination when exposing the MCP endpoints. If you run in external mode, ensure the Joplin host and port you connect to are reachable and secure.

Troubleshooting and tips

If you encounter port conflicts with an existing Joplin Desktop instance, the sidecar will automatically select the next available port. Ensure both instances use the same sync target to stay in sync.

Notes about usage with WSL and cloud sync

When running in WSL, the server resolves paths between Linux and Windows filesystems and can synchronize to OneDrive or other cloud storage. For cloud synchronization, you can use the joplin-cloud backend with the appropriate credentials.

MDX and tools

The server exposes a set of tools to interact with Joplin data via MCP, including listing notebooks, searching notes, reading content, creating and editing notes and folders, deleting content, and triggering synchronization.

Available tools

list_notebooks

Retrieve the complete notebook hierarchy

search_notes

Search for notes by query string

read_notebook

Read contents of a specific notebook

read_note

Read full content of a specific note

read_multinote

Read multiple notes at once

create_note

Create a new note

create_folder

Create a new notebook

edit_note

Edit an existing note

edit_folder

Edit an existing notebook

delete_note

Delete a note (requires confirmation)

delete_folder

Delete a notebook (requires confirmation)

sync

Trigger sync (auto-syncs every 5 min by default)