Obsidian MCP Server

Open source · Python · MCP. Разбор опубликованной версии 4ac3c0f3. Основной сценарий здесь — локальное подключение через stdio.

Заметки как источник, на который можно сослаться

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

Моя часть проекта — файловый сервис, шесть MCP-инструментов и упаковка для запуска. Агент выбирает действия и формулирует ответ; сервер выполняет конкретные операции. Такое разделение позволяет проверить, откуда взят фрагмент и какой файл изменится, прежде чем принимать предложенную правку.

Найти решение и проверить оригинал

Пример задачи: найти заметку о выборе базы для истории. vault_glob показывает пути в известной папке. vault_search ищет текст по vault, а vault_read открывает выбранный документ целиком. Совпадение строки — указатель на источник; контекст решения нужно читать отдельно.

{
  "name": "vault_search",
  "arguments": {"query": "PostgreSQL"}
}

{
  "matches": [{
    "path": "Projects/decision.md",
    "line": 2,
    "content": "Use PostgreSQL for history."
  }],
  "total_files": 2
}

Это результат проверки на двух синтетических заметках. В Projects/decision.md вторая строка содержит показанный текст. total_files здесь означает количество обработанных файлов, а не число найденных совпадений. Номер строки начинается с единицы. Эти детали помогают агенту дать проверяемую ссылку вместо пересказа без источника.

Три инженерных решения

Отделить файловую модель от MCP

VaultService отвечает за чтение, запись, перечисление, glob, дерево и текстовый поиск. Тонкие обработчики MCP передают аргументы и возвращают результат. Файловую логику можно проверять на временной директории без AI-клиента. Ошибки отсутствующего файла преобразуются в короткие сообщения без абсолютного пути хоста.

Начать с прозрачного текстового поиска

Поиск проходит по Markdown и возвращает путь, строку и её содержимое. Он поддерживает выбор чувствительности к регистру, но не вычисляет embeddings и не ранжирует документы по смысловой близости. Результат легко проверить и не нужно поддерживать отдельный индекс. Цена этого решения — повторное чтение файлов: на большом vault оно не заменяет специализированную поисковую систему.

Сделать семантику записи явной

vault_write создаёт родительские папки и записывает весь документ; существующий файл перезаписывается. Здесь нет автоматического merge, контроля версии или отмены. Для первого подключения я предлагаю копию vault и read-only mount Docker. Инструмент записи останется в каталоге, но файловая система отклонит попытку изменения. Для редактирования нужны отдельное разрешение на запись и собственная история файлов.

Что можно проверить в коде

При подготовке кейса я вызвал текущие обработчики vault_glob, vault_search, vault_read и vault_write на временных заметках в контейнере без сети. Поиск вернул показанную строку, чтение сохранило содержимое, запись создала отдельный черновик. Это проверка обработчиков; она не подтверждает совместимость каждого desktop-клиента или сетевой авторизации.

В репозитории доступны обработчики MCP, реализация поиска и тест формы результата. Отдельные тесты описывают Unicode, вложенные папки и перезапись. Количество сэкономленных запросов или времени работы я здесь не измерял.

Границы текущей версии

Это инструмент для доверенного локального окружения, а не изоляция независимых пользователей. Проверки путей не заменяют защиту от символических ссылок и файловых гонок. Сетевой SSE-режим реализован, однако authorization endpoint автоматически одобряет запрос, без пользовательского входа и экрана согласия. Для публичного доступа эта часть требует отдельной доработки и проверки.

Попробовать на отдельном vault

Собери образ и создай тестовую папку с несколькими заметками:

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

Для клиента с поддержкой stdio используй следующие параметры процесса, заменив абсолютный путь на свою тестовую папку. Read-only mount намеренно ограничивает этот пример чтением:

{
  "command": "docker",
  "args": [
    "run", "--rm", "-i", "--network", "none",
    "-e", "MCP_TRANSPORT=stdio",
    "--mount", "type=bind,src=/absolute/path/demo-vault,dst=/vault,readonly",
    "obsidian-agent-mcp"
  ]
}

Первый запрос: «Найди PostgreSQL, покажи путь и строку, затем прочитай документ; ничего не меняй». Статья о подключении Obsidian MCP объясняет работу с клиентом. После проверки чтения можно отдельно решить, нужен ли доступ к записи.