Joplin MCP

Un servidor MCP que expone una colección de notas de Joplin como un conjunto de herramientas, que se ejecuta como un agente con estado en Cloudflare Workers. Apunta un cliente MCP (Claude, etc.) al endpoint desplegado y podrá explorar libretas y notas, y crear/actualizar/eliminar notas y libretas directamente contra tu propia instancia de Joplin.

Cómo funciona

Cada llamada a una herramienta va directamente a la Joplin Data API de tu instancia activa; no hay ningún índice ni ninguna caché en medio. La propia Joplin Data API nunca se expone a Internet: el Worker accede a ella de forma privada mediante una vinculación de Workers VPC Service a través de un 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 es un McpAgent alojado en un Durable Object.

Related MCP server: Capacities MCP Worker

Herramientas

Cada herramienta que admite una nota o libreta acepta un nombre con la misma facilidad que un ID hexadecimal de 32 caracteres, de modo que el agente que la invoca no tenga que gastar un viaje de ida y vuelta buscando un ID. Los nombres se comparan de forma aproximada (se ignoran mayúsculas, acentos, puntuación y el orden de las palabras); cuando un nombre es realmente ambiguo, la herramienta devuelve los candidatos con sus IDs en lugar de adivinar.

Las notas y libretas en la papelera se excluyen de todos los resultados — listados, búsqueda y lecturas directas por igual.

Menos viajes de ida y vuelta

Las herramientas están diseñadas para que un agente pueda llegar a la nota que quiere en el menor número de llamadas posible. Leer una nota por nombre es una llamada en lugar de tres:

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

y añadir una línea a la nota es una llamada en lugar de dos, porque append realiza la operación de lectura-modificación-escritura en el servidor:

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

La resolución de nombres pasa por el propio índice de búsqueda de Joplin, por lo que normalmente cuesta una sola llamada a la API; un índice local de títulos solo se construye cuando la búsqueda no devuelve resultados (erratas o títulos que el índice de texto completo tokeniza de forma extraña). La lista de libretas se guarda en caché en el Durable Object, por lo que resolver un nombre de libreta suele ser gratuito.

Configuración

npm install

Antes de desplegar, tu Joplin Data API debe ser accesible desde un Cloudflare Tunnel, registrado como un 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>

A continuación, vincula el ID de servicio resultante en wrangler.jsonc:

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

JOPLIN_API_TOKEN (un token de la Joplin Data API) se lee desde el Secrets Store de Cloudflare, no de un secreto Wrangler normal. Créalo una vez por cuenta y se puede reutilizar entre Workers:

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

wrangler.jsonc lo vincula después mediante secrets_store_secrets:

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

Para el desarrollo local, crea un secreto solo local con el mismo nombre (omite --remote) para que wrangler dev tenga algo que leer.

Libreta predeterminada

Las herramientas que aceptan una libreta recurren a la que nombra la variable JOPLIN_DEFAULT_NOTEBOOK en wrangler.jsonc ("Default" por defecto). Apunta esta variable a la libreta en la que deben crearse las notas nuevas; si no existe ninguna libreta con ese nombre, las herramientas lo indican en lugar de elegir una.

Consulta CLAUDE.md para ver la referencia completa de la arquitectura y las vinculaciones.

Desarrollo

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

Despliegue

npm run deploy

O conecta este repositorio a un Cloudflare Worker para despliegues basados en git. En cualquier caso, el secreto joplin-token debe existir en el Secrets Store de la cuenta — nunca se almacena en el repositorio.

Tecnologías

• Cloudflare Workers + Durable Objects (con respaldo SQLite)

• Cloudflare Agents SDK (agents/mcp)

• MCP TypeScript SDK

• TypeScript, Zod para los esquemas de entrada de las herramientas, Vitest