obsidian-cli-mcp

Сервер MCP, который предоставляет Claude и другим MCP-клиентам полный контроль над работающим хранилищем Obsidian через официальный CLI Obsidian (Obsidian 1.12+), с быстрым прямым чтением файловой системы там, где это допускает корректность.

Проект-компаньон для things-for-mac-mcp.

В чем его отличие?

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

Этот сервер направляет каждую операцию по способности:

Архитектура в точности повторяет его родственный проект:

Правило, лежащее в основе разделения: массовые чтения идут в файловую систему, потому что им нужна пропускная способность, а всё, что перемещает, переименовывает, удаляет или зависит от разрешения ссылок или состояния приложения, идёт через CLI, потому что ему нужны знания Obsidian. Адаптер файловой системы структурно не может изменять хранилище — он не экспортирует никаких функций записи.

Требования

• macOS, Windows или Linux (десктоп) с Obsidian 1.12 или новее

• Включённый CLI Obsidian: Obsidian, Настройки, Общие, Интерфейс командной строки

• Obsidian должен быть запущен. CLI является клиентом приложения, а не самостоятельным бинарником. Только для десктопа, мобильные не поддерживаются.

• Node.js 18 или новее

Установка

git clone https://github.com/jabaho9523/obsidian-cli-mcp.git
cd obsidian-cli-mcp
npm install
npm run build

Подключение к MCP-клиенту

Claude (Desktop / Code)

Добавьте в claude_desktop_config.json (Claude Desktop) или выполните claude mcp add (Claude Code):

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/obsidian-cli-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT": "YourVaultName"
      }
    }
  }
}

Используйте абсолютный путь к node, а не просто слово. Приложения, запущенные из GUI, не наследуют ваш PATH из оболочки, поэтому "command": "node" молча не сработает во многих клиентах. Найдите свой командой which node.

Установите OBSIDIAN_VAULT, если у вас больше одного хранилища. В противном случае CLI будет обращаться к тому хранилищу, которое было в фокусе последним — это ужасное свойство для автоматических записей. При одном хранилище сервер автоматически закрепляет его при запуске.

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

Защитные ограничения

Три уровня, проверяемые до запуска бинарника:

• Уровень 1, свободный: чтение, поиск и аддитивные записи (create_note, append_note, append_daily, set_property, update_task, capture).

• Уровень 2, требует confirm: true в вызове инструмента: delete_note, move_note, rename_note, remove_property, run_obsidian_command и через прокси: history:restore, publish:*, plugin:enable/disable/reload, theme:*, snippet:*, sync, sync:restore, reload, template:insert, workspace:save/delete. Любой вызов, содержащий флаг overwrite или permanent, также переводится на второй уровень.

• Уровень 3, заблокирован, если сервер не запущен с OBSIDIAN_MCP_ALLOW_DANGEROUS=1: eval, restart, plugin:install, plugin:uninstall, plugins:restrict, devtools, dev:cdp, dev:debug, dev:mobile и delete_note с permanent: true.

Честное замечание о том, что это такое. Уровень 2 — это скорее препятствие против случайных вызовов, а не защита: вызывающая модель может сама установить confirm: true. Уровень 3 — реальная граница, потому что только тот, кто настраивает окружение сервера, может его разблокировать. Если вы направляете автономного агента на важное для вас хранилище, запускайте с OBSIDIAN_MCP_READONLY=1, что отклоняет любую изменяющую команду до её отправки, независимо от уровня.

Безопасные для ссылок перемещения и переименования

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

До того, с Projects/Roadmap.md, на которую ссылаются три заметки:

Weekly Review.md:   Progress on [[Roadmap]] is on track.
Team Notes.md:      See [[Roadmap#Q3]] for the plan.
Index.md:           - [[Roadmap|2026 roadmap]]

После move_note с to: "Archive/2026 Roadmap.md":

Weekly Review.md:   Progress on [[2026 Roadmap]] is on track.
Team Notes.md:      See [[2026 Roadmap#Q3]] for the plan.
Index.md:           - [[2026 Roadmap|2026 roadmap]]

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

Зачем гибрид? Обоснование производительности

Каждый вызов CLI — это один полный цикл IPC через работающее приложение Obsidian. Это корректно, но медленно: чтение 2000 заметок через obsidian read — это 2000 циклов, минуты реального времени. Чтение с диска — один обход каталога, менее секунды на любом SSD.

Поэтому массовые чтения (поиск, списки, сканирование тегов и свойств, экспорт, дайджесты) идут в файловую систему, а CLI зарезервирован для того, что может ответить только Obsidian (ссылки, алиасы, Bases, шаблоны, состояние приложения) и для всех записей. Чтобы сравнить на своём хранилище, замерьте время search_notes против прокси obsidian_cli с ["search", "query=..."].

Устранение неполадок

"Obsidian не запущен." Самая частая ошибка. CLI требует, чтобы приложение было открыто и полностью загружено. Запустите Obsidian и повторите попытку.

"Не удалось найти бинарник CLI Obsidian." Включите CLI в Obsidian: Настройки, Общие, Интерфейс командной строки, или укажите OBSIDIAN_BIN на бинарник.

Тайм-ауты при первой команде. Холодный старт Obsidian может превышать тайм-аут по умолчанию (20 с). Увеличьте OBSIDIAN_MCP_TIMEOUT.

Заметки читаются как отсутствующие, или сервер часто переключается на CLI. Если ваше хранилище находится в iCloud с включённой оптимизацией хранения Mac, вытесненные файлы существуют только в виде заглушек .name.icloud. Сервер обнаруживает их и читает через Obsidian, который загружает их снова, вместо того чтобы сообщать о пустых заметках. Массовые сканирования пропускают вытесненные файлы и сообщают об этом в выводе.

Записи попадают не в то хранилище. У вас несколько хранилищ и не задан OBSIDIAN_VAULT. Сервер предупреждает об этом в stderr при запуске. Закрепите одно.

Инструменты не отображаются в клиенте. Проверьте логи MCP клиента и проверьте проблему с абсолютным путём к node, описанную выше.

Обновление

git pull && npm install && npm run build

Сервер проверяет наличие обновлений при запуске, максимум раз в 24 часа, кэшируя результат в ~/.config/obsidian-cli-mcp/update-check.json. В автономном режиме он молча не срабатывает и выводит одну строку в stderr, если доступна более новая версия.

Инструменты (всего 39)

Инструменты для чтения (18)

Инструменты для записи (16)

Все записи проходят через CLI. Каждый требует явного указания цели file или path, ни один не может переключиться на текущий активный файл.

run_obsidian_command — самая широкая дверь в сервере: он достигает всех действий палитры команд, включая зарегистрированные плагинами сообщества. Он предоставлен намеренно и ограничен вторым уровнем защиты.

Инструменты для рабочих процессов (4)

Запасной выход (1)

MCP Ресурсы

Поддержка ресурсов клиентами различается, Claude Desktop в настоящее время их не отображает.

MCP Подсказки

Архитектура

src/
├── index.ts              MCP server entry, stdio transport
├── config.ts             Environment configuration
├── adapters/
│   ├── cli.ts            execFile wrapper, vault injection, error contract
│   └── filesystem.ts     Read-only vault access, iCloud stub detection
├── tools/
│   ├── common.ts         Shared note loading with CLI fallback
│   ├── read.ts           18 read tools
│   ├── write.ts          16 write tools
│   ├── workflow.ts       4 composite tools
│   └── passthrough.ts    obsidian_cli escape hatch
├── resources/
│   └── vault.ts          MCP resources
├── prompts/
│   └── workflows.ts      MCP prompts
└── utils/
    ├── guardrails.ts     Tier policy, readonly allowlist
    ├── markdown.ts       Frontmatter, headings, tags, word counts
    ├── output.ts         Truncation at 60,000 characters
    └── update-check.ts   Daily update check

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

npm test

Поддержка

Проблемы и запросы функций: GitHub issues.

Ещё от автора

• things-for-mac-mcp, родственный MCP-сервер для Things 3

Лицензия

MIT