What can you do with this server?

The Joplin MCP Server provides a comprehensive MCP (Model Context Protocol) interface for managing Joplin notes and notebooks. It enables you to: Read & Search * List complete notebook hierarchies * Search for notes using queries * Read individual notes or multiple notes at once * Read notebook contents Create Content * Create new notes with attributes like title, body, todo status, HTML body, parent notebook, and image data * Create new folders/notebooks with optional parent relationships Edit Content * Update existing notes (title, body, todo status, due date, completion status, parent notebook) * Edit folders/notebooks (title, parent folder) Delete Content * Delete notes and folders/notebooks (both require confirmation, with optional force deletion for folders) This server essentially provides full CRUD (Create, Read, Update, Delete) operations for your Joplin workspace through a programmatic interface.

Which integrations are available for this server?

Enables loading configuration from environment files, supporting custom environment file paths for flexible configuration management. Provides tools for interacting with Joplin notebooks and notes, including listing notebooks, searching notes, reading notebook contents, and accessing individual or multiple notes with their full content. Server implementation is built on Node.js, allowing the MCP server to run in Node.js environments. Enables installation and execution via npm's package manager, supporting both local installation and execution via npx without installation.

How do I use joplin-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@joplin-mcp-server find my meeting notes from last week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

joplin-mcp-server

by jordanburke

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

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.

Related MCP server: Jopmcp

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

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

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:

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

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

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

Tool	Description
`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)

Development

pnpm install          # Install dependencies
pnpm build            # Build to dist/
pnpm test             # Run tests
pnpm validate         # Format + lint + typecheck + test + build
pnpm serve:dev        # Dev mode with hot reload (stdio)
pnpm serve:dev:http   # Dev mode with hot reload (HTTP)
pnpm inspect          # Build and open MCP Inspector

License

MIT

Available Tools

11 tools

create_folderC

Create a new folder/notebook in Joplin

Inputs: title (required), parent_id.

create_noteC

Create a new note in Joplin

Inputs: body, body_html, image_data_url, is_todo, +2 more.

delete_folderA

Delete a folder/notebook from Joplin (requires confirmation)

Inputs: folder_id (required), confirm, force.

delete_noteB

Delete a note from Joplin (requires confirmation)

Inputs: note_id (required), confirm.

edit_folderC

Edit/update an existing folder/notebook in Joplin

Inputs: folder_id (required), parent_id, title.

edit_noteC

Edit/update an existing note in Joplin

Inputs: note_id (required), body, body_html, is_todo, +4 more.

list_notebooksB

Retrieve the complete notebook hierarchy from Joplin

Inputs: no named parameters.

read_multinoteC

Read the full content of multiple notes at once

Inputs: note_ids (required).

read_noteC

Read the full content of a specific note

Inputs: note_id (required).

read_notebookC

Read the contents of a specific notebook

Inputs: notebook_id (required).

search_notesC

Search for notes in Joplin and return matching notebooks

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

A3.5/5.0

Scored 2026-04-18 09:50 across 11 tools

Disambiguation5/5

Every tool has a clearly distinct purpose with no ambiguity. Tools are organized around specific resources (folders/notebooks, notes) and actions (create, delete, edit, list, read, search), making it easy for an agent to select the right tool for any task.

Naming Consistency5/5

Tool names follow a consistent verb_noun pattern throughout (e.g., create_folder, delete_note, edit_note, list_notebooks). All tools use snake_case and clear, descriptive verbs that match their actions precisely.

Tool Count5/5

With 11 tools, this server is well-scoped for managing Joplin notes and notebooks. Each tool earns its place by covering essential CRUD operations and additional utilities like search and multi-note reading, without being overwhelming or too sparse.

Completeness5/5

The toolset provides complete CRUD/lifecycle coverage for both folders/notebooks and notes, including create, read, edit, delete, list, and search operations. There are no obvious gaps, ensuring agents can handle all core workflows without dead ends.

Maintenance

ActivitySlowing

ResponsivenessLimited data

Resources

Related MCP Connectors

Related MCP Servers

mcp-server-docker
Virtualization Developer Tools App Automation
nideil
A
license
Not graded
quality
D
maintenance
Docker's MCP Server
Updated 2 years ago (2025-05-06 15:31 UTC)
5
MIT
Jopmcp
JPFrancoia
F
license
Not graded
quality
D
maintenance
A MCP server for Joplin note-taking application that enables interaction with Joplin notes through the web clipper API, supporting notebook hierarchy and running in Docker.
Updated a year ago (2025-08-24 17:39 UTC)
-
Joplin MCP Server
Note Taking Knowledge & Memory
Darkflib
F
license
Not graded
quality
B
maintenance
MCP server that provides standardized tools for querying and retrieving notes from Joplin personal knowledge manager through its API, enabling AI assistants to access and reference personal notes contextually.
Updated 4 days ago (2026-11-07 00:13 UTC)
9
-
Joplin Server MCP
Note Taking Knowledge & Memory
Alexander-Zhukov
A
license
Not graded
quality
B
maintenance
MCP server for Joplin Server that gives LLMs full access to notes, notebooks, tags, and attachments via the REST API.
Updated 2 months ago (2026-09-23 09:10 UTC)
7
MIT

Joplin MCP Server

Quick Start

Architecture

Sidecar Mode (Default)

External Mode

Configuration

Environment Variables

Command Line Options

Path Expansion

Sync Targets

S3-compatible providers

MCP Client Configuration

Claude Code

Claude Desktop

With Sync (Claude Desktop)

External Mode

Docker

WSL Setup

Filesystem Sync via OneDrive (Recommended)

Cloud Sync

External Mode (Port Forwarding)

Available Tools

Development

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-server-docker

Jopmcp

Joplin MCP Server

Joplin Server MCP