Joplin MCP Server

Search, read, create, edit and sync Joplin notes and notebooks via a headless Joplin sidecar.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

Terminal

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.

bash

# 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.

bash

# 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

Variable	Description	Default
`JOPLIN_TOKEN`	API token (required)	--
`JOPLIN_HOST`	Connect to existing Joplin at this host (skips sidecar)	--
`JOPLIN_PORT`	Connect to existing Joplin on this port (skips sidecar)	--
`JOPLIN_CLI`	Path to joplin CLI binary (overrides auto-detection)	--
`JOPLIN_PROFILE`	Joplin data directory for sidecar mode	`~/.config/joplin-mcp`
`JOPLIN_SYNC_TARGET`	Sync target type	`none`
`JOPLIN_SYNC_PATH`	Sync target URL/path	--
`JOPLIN_SYNC_USERNAME`	Sync username/email	--
`JOPLIN_SYNC_PASSWORD`	Sync password	--
`JOPLIN_SYNC_REGION`	S3 region	`us-east-1`
`JOPLIN_SYNC_ENDPOINT`	S3 endpoint URL (for non-AWS providers)	AWS S3
`JOPLIN_SYNC_FORCE_PATH_STYLE`	Use path-style S3 URLs (`true`/`false`)	`false`
`LOG_LEVEL`	Log level: debug, info, warn, error	`info`

Command Line Options

Code

OPTIONS:
  --env-file <file>          Load environment variables from file
  --token <token>            Joplin API token
  --transport <type>         Transport type: stdio (default) or http
  --http-port <port>         HTTP server port (default: 3000, only with --transport http)
  --profile <dir>            Joplin data directory (default: ~/.config/joplin-mcp)
  --sync-target <type>       Sync target: none, filesystem, webdav, nextcloud,
                             joplin-cloud, joplin-server, s3, dropbox, onedrive
  --sync-path <url>          URL or path for sync target
  --sync-username <user>     Username/email for sync
  --sync-password <pass>     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:

bash

# 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/<user>/.... This means --sync-path ~/OneDrive/Apps/Joplin just works on WSL without needing the full /mnt/c/... path.

Sync Targets

Target	Required Options
`none`	(default, no sync)
`filesystem`	`--sync-path /path/to/dir`
`webdav`	`--sync-path <url>` `--sync-username` `--sync-password`
`nextcloud`	`--sync-path <url>` `--sync-username` `--sync-password`
`joplin-cloud`	`--sync-username` `--sync-password`
`joplin-server`	`--sync-path <url>` `--sync-username` `--sync-password`
`s3`	`--sync-path <bucket>` `--sync-username <access-key>` `--sync-password <secret-key>`
`dropbox`	(OAuth flow)
`onedrive`	(OAuth flow)

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:

bash

# 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 <access-key> --sync-password <secret-key>

# 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 <access-key> --sync-password <secret-key>

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:

config.json

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

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

server.ts

export JOPLIN_TOKEN="your_actual_token_here"

Claude Desktop

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

config.json

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

With Sync (Claude Desktop)

config.json

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

External Mode

config.json

{
  "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

Terminal

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.

bash

# 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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Knowledge & Memory View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Joplin MCP Server

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "joplin-mcp-server": { "command": "npx", "args": ["-y", "joplin-mcp-server"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Joplin MCP Server AllMCPs Directory Badge

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/joplin-mcp-server?style=directory)](https://allmcps.com/mcp/joplin-mcp-server)

HTML Embed

<a href="https://allmcps.com/mcp/joplin-mcp-server"><img src="https://allmcps.com/api/badge/joplin-mcp-server?style=directory" alt="Joplin MCP Server on AllMCPs" /></a>

Technical Specs & Signals

CategoryKnowledge & Memory

39Quality signal: Fair · 39/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools16/30

Adoption & activity3/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

AllMCPs Server

The official MCP server for AllMCPs.com - submit and manage tools directly from your AI. The open directory for MCP servers. Connect Claude, Cursor, Windsurf, and AI agents to databases, tools, files, and APIs. Explore 10,000+ servers. AllMCPs is the premier, open directory for discovering, evaluating, and installing Model Context Protocol (MCP) servers to equip AI agents and LLMs with real-world superpowers.

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🧠 Knowledge & Memory →Best MCP servers for Memory & Knowledge →Alternatives to Joplin MCP Server →Install in Claude Desktop Install in Cursor Install in VS Code

Joplin MCP Server

Search, read, create, edit and sync Joplin notes and notebooks via a headless Joplin sidecar.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

Joplin MCP Server

Quick Start

Terminal

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.

bash

# 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.

bash

# 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

Variable	Description	Default
`JOPLIN_TOKEN`	API token (required)	--
`JOPLIN_HOST`	Connect to existing Joplin at this host (skips sidecar)	--
`JOPLIN_PORT`	Connect to existing Joplin on this port (skips sidecar)	--
`JOPLIN_CLI`	Path to joplin CLI binary (overrides auto-detection)	--
`JOPLIN_PROFILE`	Joplin data directory for sidecar mode	`~/.config/joplin-mcp`
`JOPLIN_SYNC_TARGET`	Sync target type	`none`
`JOPLIN_SYNC_PATH`	Sync target URL/path	--
`JOPLIN_SYNC_USERNAME`	Sync username/email	--
`JOPLIN_SYNC_PASSWORD`	Sync password	--
`JOPLIN_SYNC_REGION`	S3 region	`us-east-1`
`JOPLIN_SYNC_ENDPOINT`	S3 endpoint URL (for non-AWS providers)	AWS S3
`JOPLIN_SYNC_FORCE_PATH_STYLE`	Use path-style S3 URLs (`true`/`false`)	`false`
`LOG_LEVEL`	Log level: debug, info, warn, error	`info`

Command Line Options

Code

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

Path Expansion

bash

# 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.

Sync Targets

Target	Required Options
`none`	(default, no sync)
`filesystem`	`--sync-path /path/to/dir`
`webdav`	`--sync-path <url>` `--sync-username` `--sync-password`
`nextcloud`	`--sync-path <url>` `--sync-username` `--sync-password`
`joplin-cloud`	`--sync-username` `--sync-password`
`joplin-server`	`--sync-path <url>` `--sync-username` `--sync-password`
`s3`	`--sync-path <bucket>` `--sync-username <access-key>` `--sync-password <secret-key>`
`dropbox`	(OAuth flow)
`onedrive`	(OAuth flow)

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:

bash

# 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 <access-key> --sync-password <secret-key>

# 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 <access-key> --sync-password <secret-key>

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:

config.json

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

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

server.ts

export JOPLIN_TOKEN="your_actual_token_here"

Claude Desktop

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

config.json

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

With Sync (Claude Desktop)

config.json

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

External Mode

config.json

{
  "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

Terminal

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

WSL Setup

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.

bash

# 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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Knowledge & Memory View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Joplin MCP Server

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "joplin-mcp-server": { "command": "npx", "args": ["-y", "joplin-mcp-server"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/joplin-mcp-server?style=directory)](https://allmcps.com/mcp/joplin-mcp-server)

HTML Embed

<a href="https://allmcps.com/mcp/joplin-mcp-server"><img src="https://allmcps.com/api/badge/joplin-mcp-server?style=directory" alt="Joplin MCP Server on AllMCPs" /></a>

Technical Specs & Signals

CategoryKnowledge & Memory

39Quality signal: Fair · 39/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools16/30

Adoption & activity3/15

Community engagement0/10

★ Featured

AllMCPs Server

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🧠 Knowledge & Memory →Best MCP servers for Memory & Knowledge →Alternatives to Joplin MCP Server →Install in Claude Desktop Install in Cursor Install in VS Code