Joplin MCP Server

Model Context Protocol (MCP) сервер для доступа к Joplin с защитой конфиденциальности

Этот проект предоставляет доступ к вашим заметкам Joplin через MCP протокол с возможностью блокировки личных папок для защиты конфиденциальности при использовании с внешними LLM сервисами.

Основные возможности

• Model Context Protocol (MCP) - нативная поддержка MCP для Claude Desktop и других клиентов
• OpenAPI/REST прокси - для использования с OpenWebUI, Continue.dev и другими инструментами
• Пользовательские инструкции - кастомные файлы с вашими правилами организации заметок
• Защита конфиденциальности - блокировка личных папок от доступа LLM
• Иерархическая блокировка - блокировка папки автоматически блокирует все подпапки
• Поддержка русских имен - полная поддержка Unicode в названиях папок
• Компактный Docker образ - всего ~50MB на базе Alpine Linux
• Автодискавери портов - автоматическое определение порта Joplin

Общая конфигурация

Подготовка Joplin

1. Убедитесь что Joplin запущен с включенным Web Clipper API:
   • Откройте Joplin
   • Перейдите в Tools → Options → Web Clipper
   • Включите Enable Web Clipper Service
   • Скопируйте Authorization token

Настройка фильтров конфиденциальности

Для защиты личных данных от внешних LLM сервисов вы можете заблокировать определенные папки:

ВАЖНО: Если название папки содержит запятые, обязательно используйте экранирование с обратным слешем (

\,

), иначе папка НЕ попадет в фильтр блокировки!

КРИТИЧЕСКИ ВАЖНО - Экранирование:

• Запятая (
  ,
  ) - стандартный разделитель для папок
• Обратный слеш и запятая (
  \,
  ) - ОБЯЗАТЕЛЬНО используйте для экранирования запятых в названиях папок
• БЕЗ экранирования папки с запятыми НЕ БУДУТ заблокированы!

Примеры правильного экранирования:

Приоритет настроек:

1. Параметр командной строки
   --blocked-folders
   (самый высокий приоритет)
2. Переменная окружения
   JOPLIN_BLOCKED_FOLDERS
   (запасной вариант)

Что блокируется:

• Все заметки из указанных папок исключаются из результатов поиска
• Прямой доступ к заблокированным заметкам возвращает ошибку
• Заблокированные папки не отображаются в списках
• Иерархическая блокировка: все подпапки также блокируются автоматически
• Поддерживается указание как названий папок, так и их ID

Иерархическая блокировка: Если у вас есть структура папок:

Дневник/
├── 2025/
│   ├── Июнь/
│   │   └── Моя личная заметка
│   └── Июль/
└── 2024/

То блокировка папки "Дневник" автоматически заблокирует:

• Все подпапки: "2025", "Июнь", "Июль", "2024"
• Все заметки во всех этих папках
• Заметку "Моя личная заметка" в папке "Июнь"

Пользовательские инструкции (Custom Instructions)

Начиная с версии 2.0, Joplin MCP Server поддерживает пользовательские инструкции через параметр

Зачем нужны пользовательские инструкции?

Проблема: Встроенные технические инструкции (

• Ваших личных правилах организации заметок
• Структуре ваших папок и тегов
• Шаблонах заметок, которые вы используете
• Ваших рабочих процессах и предпочтениях

Решение: Создайте файл с вашими персональными инструкциями, и MCP клиенты (например, Claude) будут использовать их вместо стандартных технических инструкций.

Как использовать

1. Создайте файл с инструкциями (например,
   my-joplin-workflow.md
   )
2. Укажите путь к файлу через параметр
   --instructions
3. MCP клиенты автоматически получат ваши инструкции вместо стандартных

Структура файла инструкций

Ваш файл должен содержать информацию в формате Markdown:

Ежедневная заметка

Предпочтения для ИИ

При создании заметок

• Всегда указывай parentId (папку)
• Используй формат Markdown
• Добавляй дату создания в начало заметки
• Применяй соответствующие теги

При поиске

• Используй joplin_search() для поиска по содержимому
• Проверяй несколько вариантов названий
• Учитывай мою структуру папок

Полезные поля API

• fields=id,title,body,created_time,updated_time
  - для детального просмотра
• fields=id,title,parent_id
  - для быстрого списка (в ответах Joplin поле всегда
  parent_id
  )
• order_by=updated_time&order_dir=DESC
  - сортировка по дате изменения

### Приоритет инструкций

1. **Наивысший приоритет**: Ваш кастомный файл (если указан через `--instructions`)
2. **Запасной вариант**: Встроенные технические инструкции

При ошибках (файл не найден, ошибка чтения) система автоматически вернется к стандартным инструкциям.

### Примеры использования

```bash
# Локальный файл
JoplinMCP --instructions "/home/user/my-joplin-workflow.md"

# В Docker контейнере (через bind mount)
docker run -v "/path/to/instructions.md:/app/instructions.md" \
  joplin-mcp-proxy --instructions "/app/instructions.md"

Готовый пример

В репозитории доступен готовый пример файла инструкций:

Скопируйте его и адаптируйте под свои нужды.

Полезные советы

• Будьте конкретными: Укажите точные названия папок и тегов, которые вы используете
• Добавьте примеры: Покажите шаблоны заметок и форматы, которые предпочитаете
• Объясните логику: Расскажите о ваших принципах организации заметок
• Обновляйте файл: По мере изменения ваших рабочих процессов обновляйте инструкции
• Используйте русский язык: Файл полностью поддерживает Unicode

Кейс 1: MCP Сервер (для Claude Desktop)

Используйте этот вариант для работы с Claude Desktop, Cursor, Cline и другими MCP-совместимыми клиентами.

Сборка проекта

Конфигурация MCP клиентов

Claude Desktop

Windows:

macOS:

Linux:

Другие MCP клиенты (MCP Entry формат)

Важные моменты для MCP

1. Экранирование в JSON: В JSON конфигах используйте двойное экранирование:
   "Мысли\\, помыслы"
2. Путь к исполняемому файлу: Укажите полный путь к скомпилированному файлу JoplinMCP
3. Пользовательские инструкции: Создайте файл с вашими правилами и укажите путь через
   --instructions
4. Токен Joplin: Обязательно укажите ваш реальный токен из Joplin
5. Перезапуск клиента: После изменения конфигурации обязательно перезапустите MCP клиент
6. Права доступа: Linux/macOS:
   chmod +x JoplinMCP

Тестирование MCP сервера

Кейс 3: Настройка в opencode

Используйте этот вариант для работы с opencode - универсальным клиентом для работы с различными LLM и MCP серверами.

Конфигурация opencode

Создайте или отредактируйте файл

Параметры конфигурации

Добавление нескольких MCP серверов

Вы можете добавить несколько MCP серверов в одну конфигурацию:

Важные замечания

1. Пути к файлам: Указывайте абсолютные пути к исполняемым файлам и инструкциям
2. Токены: Храните чувствительные данные в переменных окружения, не в конфигурационном файле
3. Права доступа: Убедитесь что исполняемые файлы имеют права на выполнение (
   chmod +x
   )
4. Перезапуск: После изменения конфигурации перезапустите opencode
5. Агенты: Можно добавить агентов в opencode, которые будут использовать Joplin как MCP сервер

Отладка и решение проблем

Типичные проблемы

1. "JOPLIN_TOKEN environment variable is not set"

   • Убедитесь что переменная окружения
     JOPLIN_TOKEN
     установлена
   • Для MCP: проверьте секцию
     env
     в конфигурации

2. "Failed to connect to Joplin"

   • Проверьте что Joplin запущен
   • Проверьте что Web Clipper включен

3. "Connection refused"

   • Проверьте
     JOPLIN_HOST
     и
     JOPLIN_PORT

4. MCP сервер не запускается в Claude Desktop

   • Проверьте путь к исполняемому файлу JoplinMCP (обычно
     src/JoplinMCP/bin/Release/net9.0/JoplinMCP
     )
   • Проверьте права на выполнение файла (Linux/macOS:
     chmod +x src/JoplinMCP/bin/Release/net9.0/JoplinMCP
     )
   • Перезапустите Claude Desktop после изменения конфигурации

5. Папки с запятыми не блокируются

   • Обязательно используйте экранирование
     \,
     вместо обычных запятых
   • Пример:
     "Мысли\\, помыслы и действия,Private"
     в JSON конфигах

6. opencode не видит MCP сервер

   • Проверьте что путь к исполняемому файлу указан правильно
   • Убедитесь что файл имеет права на выполнение
   • Проверьте синтаксис JSON конфигурации
   • Перезапустите opencode после изменений

7. MCP сервер не запускается в opencode

   • Проверьте логи в терминале opencode
   • Убедитесь что все зависимости установлены
   • Проверьте переменные окружения

Тестирование соединения

Лицензия

MIT License