Joplin MCP Server

Joplin MCP Server

A self-contained MCP (Model Context Protocol) server for Joplin. Bundles the Joplin Terminal CLI as a dependency — no desktop app, no global installs, no external processes to manage. Coexists with Joplin Desktop via automatic port negotiation.

Quick Start

npx joplin-mcp-server --token your_joplin_token

That's it. The server spawns its own Joplin Terminal instance (sidecar mode), syncs to your configured backend, and exposes your notes via MCP.

Architecture

Sidecar Mode (Default)

The server bundles joplin as an npm dependency and manages its own Joplin Terminal process. No Joplin desktop app needed — the sidecar handles everything: data storage, sync, and the REST API.

If Joplin Desktop is already running, the sidecar automatically finds a free port (scanning 41184-41193) and runs alongside it. Both instances stay in sync if configured with the same sync target.

# Basic usage — sidecar starts automatically

npx joplin-mcp-server --token your_token

With cloud sync

npx joplin-mcp-server --token your_token \ --sync-target joplin-cloud \ --sync-username user@example.com --sync-password pass

With filesystem sync (e.g. OneDrive folder)

npx joplin-mcp-server --token your_token \ --sync-target filesystem \ --sync-path /mnt/c/Users/you/OneDrive/Joplin

The Joplin CLI is resolved in this order: JOPLIN_CLI env var > node_modules/.bin/joplin (bundled) > global install > npx fallback.

Data is stored in ~/.config/joplin-mcp by default (separate from any desktop Joplin install).

External Mode

Connects to an existing Joplin instance instead of spawning a sidecar. Activated by setting JOPLIN_HOST or JOPLIN_PORT.

# Connect to Joplin desktop on another machine or Windows host

JOPLIN_HOST=192.168.0.40 JOPLIN_PORT=41184 npx joplin-mcp-server --token your_token

Configuration

Environment Variables

Command Line Options

OPTIONS:

--env-file Load environment variables from file --token Joplin API token --transport Transport type: stdio (default) or http --http-port HTTP server port (default: 3000, only with --transport http) --profile Joplin data directory (default: ~/.config/joplin-mcp) --sync-target Sync target: none, filesystem, webdav, nextcloud, joplin-cloud, joplin-server, s3, dropbox, onedrive --sync-path URL or path for sync target --sync-username Username/email for sync --sync-password Password for sync --help, -h Show help message

Path Expansion

The --profile option and the --sync-path of a filesystem sync target support ~ and environment variable expansion for cross-platform compatibility. Other targets take a URL or bucket name in --sync-path, so it is passed through untouched:

# Tilde expands to home directory (Linux, macOS, Windows)

--sync-path ~/OneDrive/Apps/Joplin

Environment variables (both forms supported)

--sync-path ${HOME}/OneDrive/Apps/Joplin --sync-path $HOME/OneDrive/Apps/Joplin

Windows example using USERPROFILE

--sync-path ${USERPROFILE}/OneDrive/Apps/Joplin

This works in MCP client configs (.mcp.json, Claude Desktop) where shell expansion isn't available.

WSL auto-detection: On WSL, if a ~/ path is empty or missing, the server automatically checks the corresponding Windows path at /mnt/c/Users/ /.... This means --sync-path ~/OneDrive/Apps/Joplin just works on WSL without needing the full /mnt/c/... path.

Sync Targets

S3-compatible providers

The s3 target defaults to AWS (https://s3.amazonaws.com/, region us-east-1). Point it at any S3-compatible provider with --sync-region and --sync-endpoint:

# Backblaze B2

joplin-mcp-server --token my_token \ --sync-target s3 --sync-path my-bucket \ --sync-region us-west-004 \ --sync-endpoint https://s3.us-west-004.backblazeb2.com \ --sync-username --sync-password

MinIO / self-hosted: path-style URLs are usually required

joplin-mcp-server --token my_token \ --sync-target s3 --sync-path my-bucket \ --sync-endpoint https://minio.example.com \ --sync-force-path-style true \ --sync-username --sync-password

Cloudflare R2 and Wasabi work the same way — set --sync-endpoint to the provider's S3 endpoint.

MCP Client Configuration

Claude Code

The repository includes a .mcp.json that works with Claude Code's env var expansion:

{

"mcpServers": { "joplin": { "command": "node", "args": ["dist/bin.js"], "env": { "JOPLIN_TOKEN": "${JOPLIN_TOKEN}" } } } }

Set JOPLIN_TOKEN in your shell (add to ~/.bashrc or ~/.zshrc):

export JOPLIN_TOKEN="your_actual_token_here"

Claude Desktop

Claude Desktop does not support ${VAR} expansion. Provide values directly:

{

"mcpServers": { "joplin": { "command": "npx", "args": ["joplin-mcp-server", "--token", "your_actual_token_here"] } } }

With Sync (Claude Desktop)

{

"mcpServers": { "joplin": { "command": "npx", "args": [ "joplin-mcp-server", "--token", "your_token", "--sync-target", "filesystem", "--sync-path", "/path/to/sync/dir" ] } } }

External Mode

{

"mcpServers": { "joplin": { "command": "npx", "args": ["joplin-mcp-server"], "env": { "JOPLIN_TOKEN": "your_actual_token_here", "JOPLIN_HOST": "192.168.0.40", "JOPLIN_PORT": "41184" } } } }

Docker

docker build -t joplin-mcp .

docker run -e JOPLIN_TOKEN=your_token -p 3000:3000 joplin-mcp

WSL Setup

Running in WSL? The sidecar architecture makes this straightforward — no Windows port forwarding needed. The server auto-detects WSL and handles path resolution between Linux and Windows filesystems.

Filesystem Sync via OneDrive (Recommended)

Both your Windows Joplin desktop and the WSL sidecar sync to the same OneDrive folder. They see the same notes without needing to talk to each other directly.

# Uses ~/OneDrive — automatically resolves to /mnt/c/Users/YourName/OneDrive on WSL

npx joplin-mcp-server --token your_token \ --sync-target filesystem \ --sync-path ~/OneDrive/Apps/Joplin

Or specify the Windows path explicitly

npx joplin-mcp-server --token your_token \ --sync-target filesystem \ --sync-path /mnt/c/Users/YourName/OneDrive/Apps/Joplin

In your Joplin desktop app, configure sync to the same OneDrive folder: Tools > Options > Synchronisation > File system > /Users/YourName/OneDrive/Apps/Joplin

Joplin Desktop coexistence: If Desktop is running on port 41184, the sidecar automatically uses the next available port. A warning is logged at startup reminding you that both instances use separate databases and need the same sync target to stay in sync.

Cloud Sync

Alternatively, both instances can sync to Joplin Cloud or any other cloud backend:

npx joplin-mcp-server --token your_token \

--sync-target joplin-cloud \ --sync-username user@example.com --sync-password pass

External Mode (Port Forwarding)

If you prefer to connect directly to Windows Joplin instead of running a sidecar:

On Windows (PowerShell as Administrator):

netsh interface portproxy add v4tov4 listenport=41184 listenaddress=0.0.0.0 connectport=41184 connectaddress=127.0.0.1

In WSL:

JOPLIN_HOST=192.168.0.40 JOPLIN_PORT=41184 npx joplin-mcp-server --token your_token

Find your Windows IP with ipconfig on Windows or cat /etc/resolv.conf | grep nameserver from WSL.

Available Tools

| edit_note | Edit an existing note