obsidian-mcp-server

MCP-сервер (Model Context Protocol) для учебного Vault в Obsidian. Предоставляет Claude доступ к поиску заметок, содержимому заметок, созданию карточек в формате Decks и планированию обучения из плагина Lerntracker.

Python, MCP SDK 2.x, транспорт stdio.

Цель

Раньше логика была реализована в двух плагинах Obsidian:

• Decks (сторонний плагин) отображает карточки, но не создаёт их — карточки писались вручную.

• Lerntracker (собственный плагин) управляет учебным прогрессом и учебным планом, но сознательно не распределяет материал по дням автоматически.

Этот сервер закрывает оба пробела: Claude может создавать карточки прямо в существующем формате файлов и вычислять учебный план, который записывается обратно в data.json плагина Lerntracker.

Related MCP server: Nexus MCP for Obsidian

Установка

cd ~/Projects/obsidian-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

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

Оба пути берутся из переменных окружения — ничего не захардкожено.

Значение по умолчанию для пути Vault подходит для Obsidian, синхронизируемого через iCloud; для другой настройки достаточно задать OBSIDIAN_VAULT_PATH.

Путь Lerntracker можно настраивать отдельно, потому что Vault-ы Obsidian могут быть вложенными: если в подпапке находится ещё один Vault, у него есть собственная data.json. По умолчанию указывается на файл главного Vault.

Инструменты

Все схемы генерируются SDK из аннотаций типов и docstring-ов — в коде нет написанного вручную JSON-схемы.

Формат карточек

create_flashcard записывает ровно тот формат, который используют существующие карточки в Vault (заголовок-абзац), дополненный вики-ссылкой на источник:

---
tags: [decks]
---

## Was ist ein Signal?

Eine zeitabhängige, messbare physikalische Größe.

Quelle: [[01_Physikalische_Schicht]]

Целевой файл определяется по папке курса исходной заметки; deck переопределяет имя файла. Если файл не существует, он создаётся с tags: [decks]. Карточка с идентичной лицевой стороной пропускается, а не создаётся дважды.

Прогресс Decks хранится в базе данных SQLite, а не в Markdown-файлах. Сервер её не трогает — история FSRS остаётся нетронутой.

Почему generate_summary сам не обобщает

У сервера нет языковой модели. Он возвращает заметку в структурированном виде (структура, показатели, полный текст); краткое содержание пишет модель на стороне клиента — то есть Claude Desktop. Затем оно сохраняется с помощью save_summary. Это обычное распределение ролей в MCP: сервер предоставляет контекст и выполняет действия, а модель формулирует.

Если бы сервер должен был вместо этого сам обобщать, ему пришлось бы вызывать Anthropic-API и понадобился бы собственный API-Key.

Логика учебного плана

generate_study_plan распределяет каждую открытую подтему по конкретным дням:

1. Курсы сортируются по дате экзамена — сначала самый ранний.

2. Конец обучения = examDate − bufferDays; буферные дни остаются свободными для повторения.

3. Учебные дни берутся из settings.weeklyHours (0 = воскресенье … 6 = суббота). Дни с 0 часов и все blockedDates пропускаются.

4. Каждая подтема требует hours_per_subtopic (по умолчанию 1,5 ч) и помещается в самый ранний день с остаточной ёмкостью. Если она не помещается в один день, она разбивается на несколько дней — плагин поддерживает несколько dates.

5. Уже отмеченные подтемы и те, у которых уже есть dates, остаются нетронутыми.

6. То, что уже не помещается до конца обучения, сообщается как предупреждение, а не молча отбрасывается.

Перед каждой операцией записи рядом с файлом создаётся резервная копия (data.backup-<Zeitstempel>.json); запись происходит атомарно через временный файл. dry_run=True только показывает план.

После записи в Obsidian нажмите Cmd+R, чтобы плагин перезагрузился.

Ресурсы

Шаблон намеренно использует {+path} (Reserved Expansion) вместо {path}. Обычные переменные шаблонов не сопоставляют слэши — с {path} любая заметка во вложенной папке молча не была бы найдена, а в Vault практически каждая заметка лежит в папке курса.

Локальное тестирование с помощью MCP Inspector

Inspector запускается через CLI SDK и открывает веб-интерфейс, в котором инструменты и ресурсы можно вызывать по отдельности. Для него нужны npx (Node.js) и uv.

source .venv/bin/activate && mcp dev main.py

Команда выводит URL вида http://localhost:6274 (с добавленным сессионным токеном). Откройте в браузере, слева нажмите Connect, затем:

• Вкладка Tools → List Tools → выберите инструмент, введите аргументы, Run Tool

• Вкладка Resources → List Resources → нажмите vault://structure

• Для шаблонного ресурса введите URI напрямую, по образцу note://<Kursordner>/Flashcards/<Datei>.md

С другим Vault:

OBSIDIAN_VAULT_PATH="$HOME/Pfad/zu/deinem/Vault" mcp dev main.py

Чтобы попробовать записывающие инструменты, стоит использовать одноразовый Vault:

OBSIDIAN_VAULT_PATH=/tmp/testvault mcp dev main.py

Подключение к Claude Desktop

Файл конфигурации: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "/Users/DEIN_NAME/Projects/obsidian-mcp-server/.venv/bin/python",
      "args": ["/Users/DEIN_NAME/Projects/obsidian-mcp-server/main.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/DEIN_NAME/Pfad/zu/deinem/Vault"
      }
    }
  }
}

Важно: используйте абсолютные пути — ~ и $HOME здесь не раскрываются. В качестве command укажите Python из venv: Claude Desktop запускает сервер без активированного окружения, простой "python3" не нашёл бы пакет mcp.

Если файл уже существует, просто вставьте запись "obsidian-vault" в существующий объект mcpServers. Затем полностью закройте Claude Desktop и запустите заново; сервер появится в меню инструментов поля ввода.

Безопасность

Каждый путь из вызова Tool или Resource проверяется относительно Vault: абсолютные пути и обход через .. отклоняются, а итоговый путь должен находиться внутри OBSIDIAN_VAULT_PATH. .obsidian, .git, .trash, .claude и node_modules исключены из поиска и перечисления структуры — иначе результаты переполнят бандлы плагинов.

save_summary не перезаписывает существующий файл, create_flashcard не создаёт дублирующую карточку, а generate_study_plan делает резервную копию data.json перед записью.

Протестировано

С mcp 2.0.0 на Python 3.14 проверены: схемы Tool, шаблоны Resource, stdio-рукопожатие с настоящим ClientSession, защита путей, а также записывающие инструменты на одноразовом Vault (включая разбиение на несколько дней, заблокированные дни, дни недели с нулевым количеством часов и случай переполнения).

Лицензия

MIT — см. LICENSE.