obsidian-mcp-server
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: Obsidian MCP Server
Установка
cd ~/Projects/obsidian-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtКонфигурация
Оба пути берутся из переменных окружения — ничего не захардкожено.
Переменная | По умолчанию | Значение |
|
| Корень Vault |
|
| База данных Lerntracker |
Значение по умолчанию для пути 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 распределяет каждую открытую подтему по конкретным дням:
Курсы сортируются по дате экзамена — сначала самый ранний.
Конец обучения =
examDate − bufferDays; буферные дни остаются свободными для повторения.Учебные дни берутся из
settings.weeklyHours(0 = воскресенье … 6 = суббота). Дни с0часов и всеblockedDatesпропускаются.Каждая подтема требует
hours_per_subtopic(по умолчанию 1,5 ч) и помещается в самый ранний день с остаточной ёмкостью. Если она не помещается в один день, она разбивается на несколько дней — плагин поддерживает несколькоdates.Уже отмеченные подтемы и те, у которых уже есть
dates, остаются нетронутыми.То, что уже не помещается до конца обучения, сообщается как предупреждение, а не молча отбрасывается.
Перед каждой операцией записи рядом с файлом создаётся резервная копия
(data.backup-<Zeitstempel>.json); запись происходит атомарно через временный файл.
dry_run=True только показывает план.
После записи в Obsidian нажмите Cmd+R, чтобы плагин перезагрузился.
Ресурсы
URI | Содержимое |
| Дерево папок Vault с количеством заметок в каждой папке |
| Содержимое отдельной заметки, только чтение |
Шаблон намеренно использует {+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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read, write, and conversationally review open-source flashcards through split read/write MCP tools.
Hosted MCP for LearnOS: search courses, lesson citations, flashcards and notes from any MCP client.
Search your Glasp web and Kindle highlights, notes, and AI memories from any MCP client. Read-only.
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables interaction with Obsidian vaults through MCP, supporting note creation from templates, link management, backlink analysis, tag operations, and automatic Map of Contents generation.117,721 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to search, read, and append content to notes in an Obsidian vault via the MCP protocol.7,721 npmBSD Zero Clause
- FlicenseNot gradedqualityCmaintenanceEnables reading, writing, searching, and managing Obsidian vault notes through MCP tools and prompts, allowing AI agents to interact with local knowledge bases.-
- FlicenseAqualityDmaintenanceExposes Obsidian notes as a semantic search and RAG knowledge base over MCP, enabling AI assistants to index, retrieve, and analyze personal notes via natural language.71-