MCP Joplin Server

Сервер протокола контекста модели (MCP), который интегрируется с заметками Joplin, позволяя ИИ-клиентам (таким как Perplexity) получать доступ к вашим блокнотам и заметкам и управлять ими через API Web Clipper в Joplin.

Функции

🔍 Функционал поиска: Поиск заметок и блокнотов
📖 Чтение контента: Получение полного содержимого конкретных заметок
📝 Функции создания: Создание новых заметок и блокнотов
✏️ Функции обновления/редактирования: Обновление содержимого заметок, добавление текста в заметки и переименование блокнотов
🗑️ Функции удаления: Удаление заметок и блокнотов (поддерживается перемещение в корзину или безвозвратное удаление)
🔄 Функционал перемещения: Перемещение заметок в другие блокноты
📋 Функционал списков: Вывод списка всех блокнотов и заметок внутри конкретных блокнотов

Требования

Joplin Desktop — убедитесь, что приложение установлено и запущено
Node.js 18+ — требуется для запуска сервера MCP
Включенный Web Clipper — активируйте службу Web Clipper в Joplin

Установка и настройка

1. Включение Joplin Web Clipper

Откройте настольное приложение Joplin
Перейдите в Инструменты → Параметры → Web Clipper
Установите флажок Включить службу Web Clipper
Запишите отображаемый номер порта (обычно 41184)
Скопируйте API-токен (если требуется аутентификация)

2. Установка MCP Joplin Server

# Clone or download this project
cd mcp-joplin

# Install dependencies
npm install

# Compile TypeScript
npm run build

3. Тестовый запуск

# Run directly (will auto-detect Joplin service)
npm start

# Or specify port
npm start -- --port 41184

# Or specify token (if needed)
npm start -- --token YOUR_API_TOKEN

# View help
npm start -- --help

4. Использование npx

# Global installation (recommended)
npm install -g .

# Then use anywhere
npx mcp-joplin

# Or run locally
npx . --port 41184

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

Настройка Perplexity или других MCP-клиентов

Добавьте следующую конфигурацию в файл конфигурации вашего MCP-клиента:

🔐 Конфигурация (требуется API-токен)

Для корректной работы этого MCP-сервера требуется API-токен Joplin:

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-joplin",
        "--port",
        "41184",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

💡 Важно: API-токен необходим для правильной работы этого MCP-сервера.

Пример конфигурации Claude Desktop

Конфигурация Claude Desktop

В файле ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "joplin": {
      "command": "npx",
      "args": [
        "/Users/yourusername/path/to/mcp-joplin",
        "--token",
        "YOUR_API_TOKEN"
      ]
    }
  }
}

Доступные инструменты MCP

1. get_note_content

Получение полного содержимого конкретной заметки

Parameters: noteId (string) - The ID of the note

2. search_notes

Поиск заметок

Parameters:
- query (string) - Search keywords
- limit (number, optional) - Result limit (default: 20)

3. search_notebooks

Поиск блокнотов

Parameters: query (string) - Search keywords

4. list_notebooks

Список всех блокнотов

Parameters: None

5. list_notes

Список заметок в конкретном блокноте

Parameters:
- notebookId (string) - The ID of the notebook
- limit (number, optional) - Result limit (default: 50)

5.1. list_sub_notebooks

Список подблокнотов внутри конкретного блокнота

Parameters:
- parentNotebookId (string) - The ID of the parent notebook

6. create_note

Создание новой заметки

Parameters:
- title (string) - Note title
- body (string) - Note content (Markdown format)
- notebookId (string, optional) - Target notebook ID

7. create_notebook

Создание нового блокнота

Parameters:
- title (string) - Notebook title
- parentId (string, optional) - Parent notebook ID (for sub-notebooks)

8. delete_note

Удаление заметки

Parameters:
- noteId (string) - ID of the note to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

9. delete_notebook

Удаление блокнота

Parameters:
- notebookId (string) - ID of the notebook to delete
- permanent (boolean, optional) - Whether to permanently delete (default: false, moves to trash)

10. move_note

Перемещение заметки в другой блокнот

Parameters:
- noteId (string) - ID of the note to move
- targetNotebookId (string) - Target notebook ID

11. update_note

Обновление заголовка и/или тела существующей заметки

Parameters:
- noteId (string) - ID of the note to update
- title (string, optional) - New note title
- body (string, optional) - New note content (full replacement, not a patch)

Примечания:

Необходимо предоставить хотя бы один из параметров: title или body
Используйте это при замене содержимого заметки или переименовании заметки

12. append_to_note

Добавление содержимого в конец существующей заметки

Parameters:
- noteId (string) - ID of the note to append to
- content (string) - Content to append
- separator (string, optional) - Separator inserted before appended content (default: "\n\n")

Примечания:

Используйте это для журналов, заметок о встречах, дополнительной информации или результатов тестов
Отдавайте предпочтение этому методу перед update_note, если цель состоит в добавлении контента без замены существующего тела заметки

13. update_notebook

Обновление заголовка существующего блокнота

Parameters:
- notebookId (string) - ID of the notebook to update
- title (string) - New notebook title

14. scan_unchecked_items

Сканирование блокнотов и подблокнотов на наличие невыполненных задач (- [ ])

Parameters:
- notebookId (string) - ID of the notebook to scan
- includeSubNotebooks (boolean, optional) - Whether to recursively scan sub-notebooks (default: true)

Семантика редактирования

Используйте update_note для замены заголовка и/или тела заметки
Используйте append_to_note для добавления контента в конец заметки с сохранением существующего содержимого
Используйте move_note для изменения блокнота, к которому относится заметка
Используйте update_notebook для переименования блокнота

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

Примеры диалогов в ИИ-клиентах:

You: "Search for notes containing 'Python'"
AI: Using search_notes tool to search for relevant notes...

You: "Create a new notebook called 'Learning Plan'"
AI: Using create_notebook tool to create a new notebook...

You: "Create a note about JavaScript in the Learning Plan notebook"
AI: Using list_notebooks to find the notebook ID, then using create_note to create the note...

You: "Show the complete content of a specific note"
AI: Using get_note_content tool to retrieve note content...

You: "Update the title of note abc123 to Weekly Review"
AI: Using update_note tool to rename the note...

You: "Append these test results to note abc123"
AI: Using append_to_note tool to add the new content to the end of the note...

You: "Rename notebook xyz789 to Project Archive"
AI: Using update_notebook tool to rename the notebook...

You: "Scan my project notebook for all uncompleted todo items"
AI: Using scan_unchecked_items tool to scan all sub-notebooks...

Устранение неполадок

Проблемы с подключением

Убедитесь, что Joplin запущен
- Настольное приложение Joplin должно оставаться открытым
Проверьте настройки Web Clipper
- Убедитесь, что служба Web Clipper включена
- Проверьте настройки порта (по умолчанию 41184)
Просмотрите сообщения об ошибках
```
# Use verbose mode to see errors
DEBUG=* npm start
```

Распространенные ошибки

"Joplin Web Clipper service not found": Убедитесь, что Joplin запущен и Web Clipper включен
"Connection refused": Проверьте правильность настроек порта
"Unauthorized" или "403 Forbidden": Требуется API-токен (см. инструкции ниже)

🔑 Требуется API-токен

Для корректной работы этого MCP-сервера требуется API-токен.

Получение API-токена

В Joplin перейдите в Инструменты → Параметры → Web Clipper
Скопируйте отображаемый токен
Добавьте --token ВАШ_ТОКЕН в команду запуска

Разработка

# Run in development mode
npm run dev

# Compile
npm run build

# Prepare for publishing
npm run prepublishOnly

Техническая архитектура

Язык: TypeScript/Node.js
MCP SDK: @modelcontextprotocol/sdk
HTTP-клиент: axios
CLI: commander
API: Joplin Web Clipper API

Технические детали

Поиск блокнотов: Из-за ограничений API поиска Joplin для поиска по папкам мы используем клиентскую фильтрацию для реализации функционала поиска блокнотов
Обработка пагинации: Автоматически обрабатывает механизм пагинации API Joplin (по умолчанию 100 элементов на страницу), обеспечивая получение полных списков блокнотов и заметок, что решает проблему неполного отображения подблокнотов
Обработка ошибок: Полноценный механизм обработки ошибок, включая ошибки API Joplin и ошибки сетевого подключения
Автоопределение: Поддерживает автоматическое определение порта Joplin Web Clipper (41184-41194)

Лицензия

MIT License

Участие в разработке

Сообщения об ошибках и Pull Requests приветствуются!

Поддержка

Если вы столкнулись с проблемами, пожалуйста:

Проверьте, нормально ли работает Joplin Web Clipper
Просмотрите сообщения об ошибках и логи
Создайте Issue с подробной информацией об ошибке