Joplin MCP

MCP-сервер, который предоставляет коллекцию заметок Joplin как набор инструментов и работает как агент с состоянием на Cloudflare Workers. Укажите MCP-клиенту (Claude и др.) на развёрнутый эндпоинт — и он сможет просматривать блокноты и заметки, а также создавать, обновлять и удалять заметки и блокноты напрямую в вашем экземпляре Joplin.

Как это работает

Каждый вызов инструмента идёт напрямую к Joplin Data API на вашем работающем экземпляре — между ними нет ни индекса, ни кэша. Сам Joplin Data API никогда не доступен из публичного интернета: Worker обращается к нему приватно через привязку Workers VPC Service поверх 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 — это McpAgent, размещённый на Durable Object.

Related MCP server: Capacities MCP Worker

Инструменты

Каждый инструмент, принимающий заметку или блокнот, так же легко принимает имя, как и 32-значный шестнадцатеричный ID, поэтому вызывающему агенту не нужно тратить лишнее обращение на поиск ID. Имена сопоставляются нечётко (регистр, диакритика, пунктуация и порядок слов игнорируются); если имя действительно неоднозначно, инструмент возвращает кандидатов с их ID, а не угадывает.

Заметки и блокноты в корзине исключаются из всех результатов — и из списков, и из поиска, и из прямых чтений.

Меньше обращений

Инструменты устроены так, чтобы агент мог добраться до нужной заметки за как можно меньшее число вызовов. Чтение заметки по имени — один вызов вместо трёх:

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

а добавление строки к ней — один вызов вместо двух, потому что append выполняет чтение-изменение-запись на стороне сервера:

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

Разрешение имён идёт через собственный поисковый индекс Joplin, поэтому обычно стоит один вызов API; локальный индекс заголовков строится только тогда, когда поиск не даёт результатов (опечатки или заголовки, которые полнотекстовый индекс разбивает на токены необычным образом). Список блокнотов кэшируется в 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>

Затем пропишите полученный Service ID в wrangler.jsonc:

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

JOPLIN_API_TOKEN (токен Joplin Data API) считывается из Cloudflare Secrets Store, а не из обычного секрета Wrangler. Создайте его один раз для аккаунта, и его можно переиспользовать в разных 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 мог его прочитать.

Блокнот по умолчанию

Инструменты, принимающие блокнот, по умолчанию используют блокнот, заданный переменной JOPLIN_DEFAULT_NOTEBOOK в wrangler.jsonc (из коробки — "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