Joplin MCP

Ein MCP-Server, der eine Joplin Notizsammlung als Tool-Set bereitstellt, läuft als zustandsbehafteter Agent auf Cloudflare Workers. Richten Sie einen MCP-Client (Claude usw.) auf den bereitgestellten Endpunkt aus, und er kann Notizbücher und Notizen durchsuchen sowie Notizen und Notizbücher direkt auf Ihrer eigenen Joplin-Instanz erstellen, aktualisieren und löschen.

So funktioniert es

Jeder Tool-Aufruf geht direkt an die Joplin Data API auf Ihrer Live-Instanz – es gibt weder Index noch Cache dazwischen. Die Joplin Data API selbst wird nie dem öffentlichen Internet ausgesetzt: Der Worker erreicht sie über eine Workers VPC Service-Binding über einen Cloudflare Tunnel.

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

JoplinMCP ist ein McpAgent, der auf einem Durable Object gehostet wird.

Related MCP server: Capacities MCP Worker

Tools

Jedes Tool, das eine Notiz oder ein Notizbuch entgegennimmt, akzeptiert einen Namen ebenso wie eine 32-stellige Hex-ID`, sodass ein aufrufender Agent keinen Round Trip investieren muss, um eine ID nachzuschlagen. Namen werden unscharf abgeglichen (Groß-/Kleinschreibung, Akzente, Satzzeichen und Wortreihenfolge spielen keine Rolle); wenn ein Name wirklich mehrdeutig ist, gibt das Tool die Kandidaten mit ihren IDs zurück, statt zu raten.

Notizen und Notizbücher im Papierkorb werden aus allen Ergebnissen ausgeschlossen – bei Auflistungen, in der Suche wie auch bei direkten Zugriffen.

Weniger Roundtrips

Die Tool-Oberfläche ist so gestaltet, dass ein Agent mit möglichst wenigen Aufrufen die gewünschte Notiz erreicht. Eine Notiz über den Namen zu lesen ist ein Aufruf statt drei:

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

und eine Zeile anzufügen ist ein Aufruf statt zwei, weil append den Read-Modify-Write serverseitig durchführt:

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

Die Namensauflösung läuft über Joplins eigenen Suchindex und kostet daher normalerweise einen einzigen API-Aufruf; ein lokaler Titelindex wird nur dann aufgebaut, wenn die Such abbrechen (Tippfehler oder Titel, die der Volltext-Index in ungewohnter Weise tokenisiert). Die Liste der Notizbücher wird im Durable Object zwischengespeichert, daher ist das Auflösen eines Notizbuch- Namens meist kostenlos.

Einrichtung

npm install

Vor der Bereitstellung muss Ihre Joplin Data API über einen Cloudflare-Tunnel erreichbar sein, der als Workers VPC Service binding registriert ist:

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>

Binden Sie dann die resultierende Service-ID in wrangler.jsonc:

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

JOPLIN_API_TOKEN (ein Joplin Data API Token) wird aus Cloudflare [Secrets Store](https://developers.cloudflare.com/secrets-store/) gelesen, nicht aus einem einzelnen Wrangler-Secret. Einmal pro Konto erstellt, ist es über mehrere Worker hinweg wiederverwendbar:

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

Anschließend bindet wrangler.jsonc ihn über secrets_store_secrets:

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

For die lokale Entwicklung: Legen Sie ein nur-lokales Secret mit demselben Namen an (ohne --remote), damit wrangler dev etwas zu lesen hat.

Standard-Notizbuch

Tools, die ein Notizbuch entgegennehmen, fallen auf das Notizbuch zurück, das über die Variable JOPLIN_DEFAULT_NOTEBOOK in wrangler.jsonc benannt wird (standardmäßig "Default"). Richten Sie es auf das Notizbuch aus, in dem neue Notizen landen sollen; falls kein Notizbuch mit diesem Namen existiert, sagen die Tools dies statt eine Auswahl zu treffen.

Siehe CLAUDE.md für die vollständige Architektur- und Bindungsreferenz.

Entwicklung

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

Deployment

npm run deploy

Alternativ können Sie dieses Repository mit einem Cloudflare Worker für Git-Deployments verbinden. In jedem Fall muss das Secret joplin-token im Secrets Store des Kontos liegen – es wird nie im Repository gespeichert.

Stack

• Cloudflare Workers + Durable Objects (SQLite-basiert)

• Cloudflare Agents SDK (agents/mcp)

• MCP TypeScript SDK

• TypeScript, Zod für Tool-Eingabeschemas, Vitest?