joplin-mcp-server

Joplin MCP サーバー

Joplin 用の自己完結型 MCP（Model Context Protocol）サーバーです。Joplin Terminal CLI を依存関係として同梱しているため、デスクトップアプリもグローバルインストールも不要で、管理が必要な外部プロセスもありません。ポートを自動ネゴシエーションするため、Joplin Desktop と共存できます。

クイックスタート

npx joplin-mcp-server --token your_joplin_token

これだけです。サーバーは独自の Joplin Terminal インスタンス（サイドカーモード）を起動し、設定済みのバックエンドと同期して、MCP 経由でノートを公開します。

アーキテクチャ

サイドカーモード（デフォルト）

サーバーは joplin を npm の依存関係として同梱し、独自の Joplin Terminal プロセスを管理します。Joplin のデスクトップアプリは不要です。サイドカーがデータの保存、同期、REST API をすべて処理します。

Joplin Desktop がすでに実行中の場合、サイドカーは自動的に空きポート（41184-41193 をスキャン）を見つけて、並行して実行します。同じ同期先が設定されていれば、両方のインスタンスは同期された状態を保ちます。

# 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 [email protected] --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

Joplin CLI は次の順序で解決されます。JOPLIN_CLI 環境変数 > node_modules/.bin/joplin（同梱） > グローバルインストール > npx フォールバック。

データはデフォルトで ~/.config/joplin-mcp に保存されます（デスクトップ版 Joplin のインストール先とは別です）。

外部モード

サイドカーを起動する代わりに、既存の Joplin インスタンスへ接続します。JOPLIN_HOST または 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

設定

環境変数

変数	説明	デフォルト
JOPLIN_TOKEN	API トークン（必須）	--
JOPLIN_HOST	このホスト上の既存の Joplin に接続（サイドカーをスキップ）	--
JOPLIN_PORT	このポート上の既存の Joplin に接続（サイドカーをスキップ）	--
JOPLIN_CLI	joplin CLI バイナリへのパス（自動検出を上書き）	--
JOPLIN_PROFILE	サイドカーモード用の Joplin データディレクトリ	~/.config/joplin-mcp
JOPLIN_SYNC_TARGET	同期先の種類	none
JOPLIN_SYNC_PATH	同期先の URL／パス	--
JOPLIN_SYNC_USERNAME	同期用ユーザー名／メールアドレス	--
JOPLIN_SYNC_PASSWORD	同期用パスワード	--
JOPLIN_SYNC_REGION	S3 リージョン	us-east-1
JOPLIN_SYNC_ENDPOINT	S3 エンドポイント URL（AWS 以外のプロバイダー用）	AWS S3
JOPLIN_SYNC_FORCE_PATH_STYLE	パス形式の S3 URL を使用（true／false）	false
LOG_LEVEL	ログレベル：debug、info、warn、error	info

コマンドラインオプション

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

パスの展開

--profile オプションと、filesystem 同期ターゲットの --sync-path は、クロスプラットフォーム互換性のために ~ と環境変数の展開をサポートしています。それ以外のターゲットでは、--sync-path に URL またはバケット名を指定するため、そのまま渡されます。

# 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

これは、シェルによる展開が利用できない MCP クライアントの設定（.mcp.json、Claude Desktop）でも機能します。

WSL の自動検出： WSL では、~/ パスが空または存在しない場合、サーバーは対応する Windows パス（/mnt/c/Users/<user>/...）を自動的に確認します。そのため、WSL では --sync-path ~/OneDrive/Apps/Joplin を指定するだけで、/mnt/c/... のフルパスを指定する必要なく動作します。

同期ターゲット

ターゲット	必須オプション
none	（デフォルト、同期なし）
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 フロー）
onedrive	（OAuth フロー）

S3 互換プロバイダー

s3 ターゲットは、デフォルトで AWS（https://s3.amazonaws.com/、リージョン us-east-1）を使用します。--sync-region と --sync-endpoint を指定すると、任意の S3 互換プロバイダーを指定できます。

# 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 と Wasabi も同様に利用できます。--sync-endpoint にプロバイダーの S3 エンドポイントを設定してください。

MCP クライアントの設定

Claude Code

このリポジトリには、Claude Code の環境変数展開に対応した .mcp.json が含まれています。

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

シェルで JOPLIN_TOKEN を設定します（~/.bashrc または ~/.zshrc に追加してください）。

export JOPLIN_TOKEN="your_actual_token_here"

Claude Desktop

Claude Desktop は ${VAR} の展開に対応していません。値を直接指定してください。

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

同期を使用する場合（Claude Desktop）

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

外部モード

{
  "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 のセットアップ

WSL で実行しますか？ サイドカーアーキテクチャにより簡単に設定できます。Windows のポート転送は不要です。サーバーは WSL を自動検出し、Linux と Windows のファイルシステム間のパス解決を処理します。

OneDrive 経由のファイルシステム同期（推奨）

Windows 上の Joplin デスクトップアプリと WSL のサイドカーが、同じ OneDrive フォルダーに同期します。両者が直接通信する必要なく、同じノートを参照できます。

# 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

Joplin デスクトップアプリで、同じ OneDrive フォルダーへの同期を設定します：Tools > Options > Synchronisation > File system > /Users/YourName/OneDrive/Apps/Joplin

Joplin Desktop との併用： Desktop がポート 41184 で実行中の場合、サイドカーは自動的に次に利用可能なポートを使用します。起動時に警告が記録され、両方のインスタンスは別々のデータベースを使用するため、同期を保つには同じ同期ターゲットが必要であることが通知されます。

クラウド同期

別の方法として、両方のインスタンスを Joplin Cloud またはその他のクラウドバックエンドに同期できます。

npx joplin-mcp-server --token your_token \
  --sync-target joplin-cloud \
  --sync-username [email protected] --sync-password pass

外部モード（ポート転送）

サイドカーを実行する代わりに Windows の Joplin に直接接続する場合：

Windows 上（管理者として PowerShell を実行）：

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

WSL 内：

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

Windows で ipconfig を実行するか、WSL から cat /etc/resolv.conf | grep nameserver を実行すると、Windows の IP アドレスを確認できます。

利用可能なツール

ツール	説明
list_notebooks	ノートブックの階層全体を取得します
search_notes	クエリ文字列でノートを検索します
read_notebook	特定のノートブックの内容を読み取ります
read_note	特定のノートの全内容を読み取ります
read_multinote	複数のノートを一度に読み取ります
create_note	新しいノートを作成します
create_folder	新しいノートブックを作成します
edit_note	既存のノートを編集します
edit_folder	既存のノートブックを編集します
delete_note	ノートを削除します（確認が必要です）
delete_folder	ノートブックを削除します（確認が必要です）
sync	同期を開始します（デフォルトでは5分ごとに自動同期します）

開発

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

ライセンス

MIT