Joplin MCP

An MCP server that exposes a Joplin note collection as a tool set, running as a stateful agent on Cloudflare Workers. Point an MCP client (Claude, etc.) at the deployed endpoint and it can browse notebooks and notes, and create/update/delete notes and notebooks directly against your own Joplin instance.

How it works

Every tool call goes straight to the Joplin Data API on your live instance — there's no index or cache in between.

MCP client ──HTTP/SSE──► Worker (/mcp) ──► JoplinMCP (Durable Object)
                                                  │
                                    JoplinClient ──► Joplin Data API

JoplinMCP is a McpAgent hosted on a Durable Object.

Related MCP server: Capacities MCP Worker

Tools

Setup

npm install

Before deploying, set vars.JOPLIN_CLIENT_URL in wrangler.jsonc to the base URL of your Joplin Data API.

JOPLIN_API_TOKEN (a Joplin Data API token) is read from Cloudflare's Secrets Store, not a plain Wrangler secret. Create it once per account and it's reusable across Workers:

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

wrangler.jsonc then binds it via secrets_store_secrets:

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

For local dev, create a local-only secret with the same name (omit --remote) so wrangler dev has something to read.

See CLAUDE.md for the full architecture and binding reference.

Development

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

Deploy

npm run deploy

Or connect this repository to a Cloudflare Worker for git-based deploys. Either way, the joplin-token secret must exist in the account's Secrets Store — it is never stored in the repo.

Stack

• Cloudflare Workers + Durable Objects (SQLite-backed)

• Cloudflare Agents SDK (agents/mcp)

• MCP TypeScript SDK

• TypeScript, Zod for tool input schemas, Vitest