obsidian-vault-mcp

MCP-сервер для работы с хранилищем Obsidian на сервере. Работает напрямую с markdown-файлами на диске: запущенный Obsidian не нужен, headless-режим не нужен, хранилище не отдается стороннему облаку. Транскрибация YouTube встроена: ссылка на видео превращается в конспект в том же хранилище.

English version

Зачем он нужен

Для доступа ваших агентов к хранилищу Obsidian, которое хранится не локально, а на сервере. Работайте со своей базой в связке с ИИ-агентом откуда угодно: найти по слову, прочитать заметку, дописать раздел, посмотреть обратные ссылки. Хранилище попадает на сервер целиком привычной синхронизацией (Obsidian Sync, Syncthing, git), сервер открывает к нему доступ по MCP и при этом:

• весь код читается за вечер: один компактный пакет, никакой магии, никаких сторонних сервисов между агентом и вашими файлами;

• запись безопасна: атомарные записи, проверка конфликтов, холостой режим с diff, корзина вместо удаления, журнал каждой правки (подробнее в docs/write-contract.md);

• вход только ваш: OAuth через GitHub или Google плюс список разрешенных логинов, пустой список не пускает никого. Для машинных учетных записей (агентов без браузера) есть предвыданные токены с политикой «что нельзя» (подробнее в docs/static-tokens.md);

• видео → конспект: транскрибация YouTube встроена в сервер, отдельный сервер расшифровок не нужен. Агент получает по ссылке расшифровку с названием и каналом и кладет конспект в базу.

Сервер отдает только .md-файлы и только внутри указанной папки базы: путь наружу базы невозможен, картинки и конфиги Obsidian не трогаются.

Related MCP server: Hermes Obsidian Drive MCP

Инструменты (15)

Дополнительный инструмент youtube_transcript

Отдает расшифровку видео с названием и каналом. Работоспособность зависит от того, на каком сервере хостится MCP. YouTube обычно не отдает транскрипт запросам с IP-адресов хостингов. С домашнего или офисного адреса работает, с адреса арендованного сервера (VPS) вероятны отказы; исходящий трафик можно направить через прокси переменной HTTPS_PROXY.

Структура

vault_mcp/            код сервера (пакет)
  server.py           вход, OAuth, обертки @mcp.tool
  vaultops.py         вся работа с файлами базы
  static_tokens.py    файл хешей машинных токенов
  naming.py           безопасные имена заметок
tests/                офлайн-тесты (без сети и fastmcp)
tools/                выдача токена, пробник приемки
docs/                 контракт записи, токены, подключение клиента
Dockerfile, docker-compose.yml, .env.example   деплой

Быстрый старт

Нужен сервер с Docker и домен с HTTPS (OAuth требует публичный адрес). Рядом с базой, за своим reverse-proxy (Caddy, Traefik, nginx, что угодно).

git clone https://github.com/demenn/obsidian-vault-mcp.git
cd obsidian-vault-mcp
cp .env.example .env
# заполнить: OAuth-ключи, MCP_BASE_URL, MCP_ALLOWED_USERS, HOST_VAULT
docker compose up -d --build

Как создать OAuth-приложение и заполнить .env: комментарии внутри .env.example.

Проверка, что сервер жив (одна строка; любой HTTP-код в ответе значит «жив», отказ соединения значит «не поднялся»):

curl -s -o /dev/null -w "%{http_code}\n" https://your-domain/mcp
# 401 = вход включен и закрыт, как задумано; 406 = OAuth еще не настроен

Подключение в Claude: Settings, Connectors, Add custom connector, URL https://your-domain/mcp. Для любого другого клиента и для машинных токенов: docs/connecting-a-client.md.

Без Docker: pip install . из папки репозитория, затем vault-mcp (переменные окружения те же, список в .env.example).

Переменные окружения

Основные (полный список с пояснениями в .env.example):

Тесты

Офлайн, без сети и без fastmcp (нужен только pyyaml), подойдет любой Python 3.9+:

pip install pyyaml
python3 tests/test_vaultops.py
python3 tests/test_static_tokens.py

Линтер: ruff check . (конфиг в ruff.toml).

Документация

• docs/write-contract.md: контракт записи (атомарность, expected_hash, dry_run, корзина, журнал, модель угроз)

• docs/static-tokens.md: машинные токены: выдача, ротация, политика «что нельзя»

• docs/connecting-a-client.md: подключение клиента по токену, curl, разбор отказов

Лицензия

MIT