Joplin MCP

Joplin のノートコレクションをツールセットとして公開する MCP サーバーで、Cloudflare Workers 上でステートフルエージェントとして動作します。MCP クライアント（Claude など）をデプロイ済みのエンドポイントに向けると、ノートブックやノートの閲覧に加え、ご自身の Joplin インスタンスに対してノートやノートブックの作成・更新・削除を直接行うことができます。

動作の仕組み

すべてのツール呼び出しは、稼働中のインスタンス上の Joplin Data API に直接到達します。間にインデックスやキャッシュは一切ありません。Joplin Data API 自体が公開インターネットに晒されることは決してなく、Worker は Cloudflare Tunnel を介した Workers VPC Service バインディングを通じて、プライベートにアクセスします。

MCP client ──HTTP/SSE──► Worker (/mcp) ──► JoplinMCP (Durable Object)
                                                  │
                          JoplinClient ──► JOPLIN_VPC (Workers VPC Service)
                                                  │
                          Cloudflare Tunnel ──► Joplin Data API (LAN-only)

JoplinMCP は、Durable Object 上でホストされる McpAgent です。

Related MCP server: Capacities MCP Worker

ツール

ノートまたはノートブックを受け取るすべてのツールは、32桁の16進IDと同様に名前もそのまま受け付けます。そのため、呼び出し側のエージェントはIDを調べるためのラウンドトリップを費やす必要がありません。名前はファジーマッチングされます（大文字小文字、アクセント、句読点、語順はすべて許容されます）。名前が真にあいまいな場合、ツールは推測する代わりに候補とそのIDを返します。

ごみ箱にあるノートとノートブックは、一覧表示・検索・直接読み取りのすべての結果から除外されます。

ラウンドトリップの削減

ツール群は、エージェントが目的のノートにできるだけ少ない呼び出しで到達できるように設計されています。名前でノートを読むのは、3回ではなく1回の呼び出しで済みます：

list_notebooks → list_notes → get_note      ⟶   get_note { note: "grocery list" }

また、append がサーバー側で読み取り・変更・書き込みを行うため、行を追加するのも2回ではなく1回の呼び出しで済みます：

get_note → update_note { body: <whole note> }  ⟶  update_note { note: "grocery list", append: "- milk" }

名前の解決は Joplin 自身の検索インデックスを経由するため、通常はAPI呼び出し1回分のコストで済みます。ローカルのタイトルインデックスが構築されるのは、検索結果が空になった場合（タイプミスや、全文検索インデックスが奇妙にトークン化するタイトル）だけです。ノートブックの一覧は Durable Object にキャッシュされるため、ノートブック名の解決は通常コストがかかりません。

セットアップ

npm install

デプロイする前に、Joplin Data API が Cloudflare Tunnel から到達可能であり、Workers VPC Service として登録されている必要があります：

npx wrangler vpc service create joplin-data-api \
  --type http \
  --tunnel-id <YOUR_TUNNEL_ID> \
  --hostname <JOPLIN_HOST_ON_YOUR_LAN> \
  --http-port <JOPLIN_PORT>

その後、wrangler.jsonc で生成されたサービスIDをバインドします：

"vpc_services": [
  { "binding": "JOPLIN_VPC", "service_id": "<service-id-from-above>", "remote": true }
]

JOPLIN_API_TOKEN（Joplin Data API トークン）は、通常の Wrangler シークレットではなく、Cloudflare の Secrets Store から読み取られます。アカウントごとに一度作成すれば、複数の Workers 間で再利用できます：

wrangler secrets-store secret create <store-id> \
  --name joplin-token --scopes workers --remote

wrangler.jsonc はその後、secrets_store_secrets を介してそれをバインドします：

"secrets_store_secrets": [
  { "binding": "JOPLIN_API_TOKEN", "store_id": "<store-id>", "secret_name": "joplin-token" }
]

ローカル開発では、同じ名前でローカルのみのシークレットを作成します（--remote は省略）。これにより、wrangler dev が読み取る対象を持てるようになります。

デフォルトのノートブック

ノートブックを受け取るツールは、wrangler.jsonc 内の JOPLIN_DEFAULT_NOTEBOOK 変数で指定されたノートブックにフォールバックします（初期状態では "Default"）。新しいノートを置きたい任意のノートブックを指定してください。その名前のノートブックが存在しない場合、ツールは適当に選ぶのではなく、その旨を伝えます。

完全なアーキテクチャとバインディングのリファレンスについては、CLAUDE.md を参照してください。

開発

npm run dev         # wrangler dev — local development with hot reload
npm run test        # vitest run
npm run typecheck   # tsc --noEmit

デプロイ

npm run deploy

または、このリポジトリを Cloudflare Worker に接続して、git ベースのデプロイを行うこともできます。いずれにしても、joplin-token シークレットがアカウントの Secrets Store に存在している必要があります。リポジトリ内に保存されることは決してありません。

技術スタック

• Cloudflare Workers + Durable Objects（SQLite バックエンド）

• Cloudflare Agents SDK（agents/mcp）

• MCP TypeScript SDK

• TypeScript、ツール入力スキーマ用の Zod、Vitest