Привет, Хабр!

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

И так несколько раз в день.

В какой-то момент стало понятно, что проблема не в Obsidian и не в LLM. Проблема в том, что между ними нет нормального моста.

Я храню в Obsidian рабочие заметки, идеи для статей, черновики, технические решения, куски документации, планы проектов и личную базу знаний. Но когда я работаю в Cursor или ChatGPT, вся эта база для модели как будто не существует. Она может рассуждать о чем угодно, но не видит мои реальные заметки, пока я сам не принесу ей нужный контекст.

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

Вместо того чтобы продолжать играть в человека-адаптера, я написал MCP-сервер для Obsidian. Он подключает Obsidian vault к любому LLM-клиенту с поддержкой MCP и дает модели нормальные инструменты: читать заметки, искать по ним, смотреть структуру, создавать и обновлять файлы.

Репозиторий: https://github.com/tenqz/obsidian-agent

Что я хотел решить

У меня не было цели написать очередной красивый плагин для Obsidian.

Плагины хороши, когда вы работаете внутри самого Obsidian. Но я хотел обратную задачу: чтобы мои заметки были доступны из любого инструмента, где я уже работаю с LLM.

Например:

- из Cursor, когда я пишу код и хочу подтянуть контекст из проектных заметок;

- из ChatGPT, когда нужно быстро найти старую мысль, черновик или связанный материал;

- из другого MCP-совместимого клиента, который появится завтра.

То есть мне был нужен не отдельный интерфейс, а слой интеграции.

Модель должна уметь не просто отвечать на абстрактные вопросы, а работать с конкретным хранилищем:

- показать структуру vault;

- найти заметки по названию или glob-паттерну;

- прочитать нужный markdown-файл;

- найти упоминания фразы по всему хранилищу;

- создать новую заметку;

- обновить существующую заметку.

Звучит не очень сложно. Но именно такой простой набор операций меняет сценарий работы.

Вместо вопроса: "Вот кусок текста, помоги с ним" можно спросить: "Посмотри мои заметки по проекту, найди, что я писал про архитектуру, и собери короткое резюме".

И вот это уже похоже на работу с ассистентом, который хотя бы видит тот же контекст, что и вы.

Почему MCP

Если коротко, MCP — это протокол, через который LLM-клиент может подключать внешние инструменты.

Можно воспринимать его как стандартный способ сказать модели: "Вот набор доступных действий, вызывай их, когда тебе нужен внешний контекст".

Раньше для каждой связки приходилось думать отдельно. Для одного клиента нужен плагин. Для другого — API. Для третьего — свой формат интеграции. В итоге вы быстро приходите к зоопарку адаптеров.

MCP решает эту проблему более универсально. Сервер один, клиенты разные.

В моем случае сервер предоставляет Obsidian vault как набор инструментов:

- vault_ls — посмотреть содержимое папки;

- vault_read — прочитать markdown-файл;

- vault_write — создать или перезаписать заметку;

- vault_glob — найти файлы по паттерну;

- vault_tree — получить дерево хранилища;

- vault_search — выполнить полнотекстовый поиск по markdown-файлам.

LLM-клиент видит эти инструменты и может вызывать их сам, если понимает, что без данных из vault не справится.

Почему не Obsidian-плагин

Obsidian-плагин был бы логичным вариантом, если бы задача звучала так: "Хочу AI-функции внутри Obsidian".

Но у меня задача другая.

Я не всегда работаю внутри Obsidian. Часто заметки нужны в момент, когда открыт код, документация, терминал или LLM-клиент. Не хочется каждый раз переключаться в Obsidian, искать файл, копировать куски текста и возвращаться обратно.

Поэтому я выбрал более тупой, но надежный путь: работа напрямую с файловой системой.

Obsidian vault — это обычная папка с markdown-файлами. Значит, серверу не нужен Obsidian API, Electron, плагины или какая-то внутренняя магия. Достаточно смонтировать папку в Docker-контейнер и аккуратно работать с файлами.

В этом подходе есть несколько плюсов:

- сервер не зависит от запущенного Obsidian;

- заметки остаются обычными markdown-файлами;

- можно подключаться из разных MCP-клиентов;

- проще контролировать окружение через Docker;

- легче запускать сервер там, где Obsidian вообще не установлен.

Минус тоже есть: сервер не знает всего, что знает сам Obsidian. Например, он не работает с внутренним состоянием приложения, открытыми вкладками или плагинами.

Но для моей задачи это не минус. Мне нужен был доступ к содержимому и структуре vault, а не управление интерфейсом Obsidian.

Как это устроено

Проект состоит из двух основных частей:

obsidian-agent/
├── app/
│   ├── mcp/
│   │   └── server.py      # MCP server
│   └── vault/
│       └── service.py     # операции с vault
├── tests/
│   └── test_vault_service.py
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml

Слой vault отвечает за операции с файлами: чтение, запись, обход директорий, glob-поиск и полнотекстовый поиск.

Слой mcp превращает эти операции в MCP-инструменты, которые видит клиент.

Я специально держал набор инструментов маленьким. Для LLM это важно. Чем меньше и понятнее доступные действия, тем выше шанс, что модель будет использовать их предсказуемо.

Если дать модели двадцать похожих методов, она начнет выбирать странно. Если дать шесть понятных операций, поведение становится гораздо стабильнее.

Два режима работы

У сервера есть два режима подключения: stdio и sse.

stdio — это самый простой вариант для локальных клиентов вроде Cursor или Claude Desktop. MCP-клиент запускает Docker-контейнер и общается с сервером через stdin/stdout. Наружу ничего не торчит, отдельный порт открывать не нужно.

sse — это сетевой режим через Server-Sent Events. Он нужен для сценариев, где клиент подключается по URL. Например, для ChatGPT MCP или удаленного доступа.

Для локальной работы я бы начинал именно со stdio. Он проще, безопаснее и не требует HTTPS, домена или OAuth.

Для сетевого режима уже нужны нормальные меры безопасности. Поэтому в проекте есть OAuth 2.1 с Authorization Code Flow и PKCE.

Быстрый старт для Cursor

Сначала собираем Docker-образ:

git clone https://github.com/tenqz/obsidian-agent.git
cd obsidian-agent
docker build -t obsidian-agent-mcp .

Потом добавляем MCP-сервер в настройки клиента.

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

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "MCP_TRANSPORT=stdio",
        "-v", "/path/to/your/vault:/vault",
        "obsidian-agent-mcp"
      ]
    }
  }
}

Путь /path/to/your/vault нужно заменить на путь до вашего Obsidian vault.

Например, для Windows через WSL это может быть:

/mnt/c/Users/YourName/Documents/ObsidianVault

Для macOS:

/Users/YourName/Documents/ObsidianVault

Для Linux:

/home/yourname/Documents/ObsidianVault

После этого нужно перезапустить MCP-клиент. Если все настроено правильно, клиент увидит новый сервер и его инструменты.

Что можно попросить у модели

Самый простой сценарий:

> Покажи структуру моего vault.

Клиент вызовет vault_tree, и модель сможет увидеть, как устроены папки и файлы.

Другой пример:

> Найди все заметки, где упоминается machine learning.

Для этого используется vault_search. Он проходит по markdown-файлам и возвращает совпадения с путем, номером строки и содержимым.

Еще пример:

> Найди все заметки за 2025 год.

Здесь удобнее использовать vault_glob:

**/2025-*.md

Glob-поиск оказался неожиданно важным. Без него модель часто вынуждена делать много последовательных ls-вызовов: открыть папку, посмотреть вложенные папки, пройти глубже, повторить.

vault_glob убирает большую часть таких обходов. Модель может сразу найти нужный набор файлов и дальше работать уже с ним.

Например:

Daily/2025/**/*.md
Projects/**/*.md
**/*mcp*.md

Это особенно полезно в больших vault, где структура уже перестала быть маленькой и очевидной.

Read-write доступ: полезно, но страшно

Самая чувствительная часть — запись.

Читать заметки модели дать относительно несложно. Максимум она увидит лишний контекст, если вы сами подключили весь vault. Но запись — это уже другая история.

Если модель может перезаписывать файлы, значит, она может испортить заметку. Не из злого умысла, а просто потому что неправильно поняла задачу, не дочитала контекст или решила "улучшить" то, что улучшать не просили.

Поэтому я бы не советовал бездумно давать read-write доступ ко всему хранилищу.

Нормальные варианты:

- подключать отдельный vault для экспериментов;

- монтировать только нужную папку;

- хранить заметки в git и смотреть diff перед коммитом;

- просить модель сначала показать план изменений;

- использовать read-only режим там, где запись не нужна.

Сама возможность записи очень полезна. Например, можно попросить:

> Создай черновик статьи на основе заметок из папки Research.

Или:

> Собери отдельную заметку со всеми идеями по проекту, которые разбросаны по daily notes.

Но я бы относился к этому как к работе с junior-разработчиком, которому дали доступ к репозиторию. Пусть делает полезную работу, но diff лучше посмотреть.

SSE и ChatGPT MCP

Для ChatGPT и удаленных сценариев нужен сетевой режим.

В этом случае сервер запускается с транспортом sse:

OBSIDIAN_VAULT_PATH=/path/to/your/vault
MCP_TRANSPORT=sse
MCP_PORT=8001

Если сервер доступен из интернета, обязательно нужен OAuth:

MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER=https://your-server.com

После запуска ChatGPT подключается к:

https://your-server.com/sse

Дальше он автоматически проходит OAuth-flow:

- получает metadata из well-known endpoints;

- регистрируется как OAuth client;

- выполняет Authorization Code Flow с PKCE;

- получает access token;

- подключается к SSE endpoint.

В проекте для этого есть нужные endpoints:

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server
/oauth/register
/oauth/authorize
/oauth/token
/sse

В production без HTTPS такой режим запускать не стоит. Токены и доступ к личной базе знаний — не та вещь, которую хочется гонять по открытому HTTP.

Почему OAuth 2.1

Для локального stdio режима OAuth не нужен. Сервер живет внутри контейнера, общение идет напрямую через процесс, наружу ничего не открывается.

Но как только появляется публичный URL, история меняется.

ChatGPT MCP ожидает нормальную OAuth-схему. Поэтому я сделал OAuth 2.1 с PKCE. Это не "логин ради логина", а базовая защита от ситуации, когда кто-то просто узнает URL вашего MCP-сервера и начинает читать vault.

В реализации используются:

- Authorization Code Flow;

- PKCE S256;

- Dynamic Client Registration;

- короткоживущие access tokens;

- корректные WWW-Authenticate headers для 401-ответов.

Это не отменяет общей ответственности за инфраструктуру. Нужен домен, HTTPS, нормальный reverse proxy и понимание, кому вы вообще открываете доступ.

Для интеграции с ChatGPT такой вариант уже выглядит не игрушкой, а нормальным протоколом доступа.

Примеры реальных сценариев

Самое очевидное — поиск по заметкам.

Но обычный поиск есть и в Obsidian. Интереснее становится, когда модель не просто находит файл, а делает с найденным контекстом следующую операцию.

Например:

> Найди все заметки про MCP и собери список нерешенных технических вопросов.

Или:

> Прочитай мои заметки по проекту и составь README для репозитория.

Или:

> Найди все черновики статей, где есть только идея, но нет структуры.

Или:

> Собери из daily notes все упоминания проекта за последний месяц и сделай краткий отчет.

Вот здесь и появляется главная польза.

Модель перестает быть просто генератором текста. Она начинает работать с вашим накопленным контекстом.

Что внутри по разработке

Проект написан на Python и запускается в Docker.

Основные команды:

# посмотреть доступные команды
make help

# запустить тесты с coverage
make test

# быстрый запуск тестов
make test-quick

# линтеры
make lint

# форматирование
make format

# линтеры + тесты
make check

Docker-команды:

# собрать production image
make docker-build

# поднять сервисы
make docker-up

# остановить сервисы
make docker-down

# посмотреть логи
make docker-logs

Я старался держать проект максимально прикладным. Без сложной архитектуры ради архитектуры. Есть сервер, есть сервис для vault, есть тесты на операции с файлами.

Что дальше

Сейчас сервер закрывает базовые сценарии: навигация, чтение, запись, glob и полнотекстовый поиск.

Но вокруг Obsidian можно сделать гораздо больше:

- read-only режим на уровне конфигурации;

- безопасные patch-операции вместо полной перезаписи файла;

- индексацию ссылок между заметками;

- поиск backlinks;

- работу с frontmatter;

- шаблоны для новых заметок;

- ограничения по разрешенным папкам;

- dry-run режим для записи;

- интеграцию с git, чтобы модель могла показывать diff перед сохранением.

Особенно интересна тема безопасного редактирования. Просто дать модели vault_write — рабочий вариант для черновиков, но не идеальный для важной базы знаний.

Мне кажется, правильная следующая ступень — не "модель сама все переписывает", а "модель предлагает изменения как diff, а человек подтверждает".

Итог

Я не думаю, что AI должен заменить личную базу знаний. Скорее наоборот: чем больше мы используем LLM, тем важнее становится собственный контекст.

Без него модель каждый раз начинает с нуля. С ним она может опираться на ваши решения, заметки, черновики, старые идеи и проектную историю.

MCP в этой схеме выглядит как хороший технический слой. Он не привязан к одному клиенту и не заставляет писать отдельную интеграцию под каждый инструмент.

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

А MCP-сервер просто дает LLM нормальный способ с этой папкой работать.

Ссылки:

• GitHub проекта: https://github.com/tenqz/obsidian-agent

• Model Context Protocol: https://modelcontextprotocol.io/

• Obsidian: https://obsidian.md/

• Мой блог в тг: https://t.me/opatsay

Интересно, как вы бы использовали такую связку?

Дали бы модели доступ только на чтение или разрешили бы запись? И какие ограничения считаете обязательными, если LLM получает доступ к личной базе знаний?