obsidian-cli-mcp

obsidian-cli-mcp — это MCP сервер для официального CLI Obsidian. Он предоставляет операции поиска по хранилищу Obsidian, заметкам, задачам, файлам, ссылкам и нативному Canvas для MCP-клиента. Сервер не заменяет Obsidian: CLI пересылает запросы в запущенное настольное приложение Obsidian.

Транспорт по умолчанию — локальный stdio. Удалённый Streamable HTTP доступен как дополнительная, отдельно защищённая настройка; для локального использования он не требуется.

Требования

• macOS с установленным и запущенным Obsidian Desktop.

• Официальный CLI Obsidian включён в Obsidian: Настройки → Общие → Интерфейс командной строки, затем зарегистрируйте obsidian в вашем PATH.

• Node.js 18 или новее для запуска опубликованного пакета. Bun нужен только для сборки или разработки этого исходного кода.

Этот проект требует настольный CLI. Он не поддерживает obsidian-headless. Приложение Obsidian должно оставаться открытым во время использования MCP-сервера.

Сначала проверьте сторону Obsidian:

command -v obsidian
obsidian version
obsidian vault

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

Запустите опубликованный пакет v0.4.1 из любого каталога:

npx --yes --package=@dariuscodes/obsidian-cli-mcp@0.4.1 obsidian-cli-mcp

Команда общается по MCP через stdio и ожидает MCP-клиента. Она намеренно не выводит данные протокола в терминал. Диагностика идёт в stderr.

Для исходного кода вместо этого:

git clone https://github.com/DariusCorvus/obsidian-cli-mcp.git
cd obsidian-cli-mcp
bun install --frozen-lockfile
bun run build
node dist/main.js

Для локального использования по умолчанию не требуется имя хранилища, путь к хранилищу, токен, учётная запись Cloudflare, LaunchAgent или файл конфигурации. Сервер использует активное хранилище, которое Obsidian предоставляет через официальный CLI.

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

Для клиента, который принимает конфигурацию mcpServers, используйте команду npm:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=@dariuscodes/obsidian-cli-mcp@0.4.1",
        "obsidian-cli-mcp"
      ]
    }
  }
}

Если клиент не наследует PATH вашей оболочки, замените npx на абсолютный путь, выводимый командой command -v npx. Для исходного кода используйте command: "node" и args: ["/absolute/path/to/obsidian-cli-mcp/dist/main.js"].

Перезапустите клиент после изменения его MCP-конфигурации. Первая полезная последовательность действий:

1. Вызовите vault_search с запросом, который должен существовать в вашем хранилище, например { "query": "meeting", "limit": 10 }.

2. Передайте один из возвращённых путей в note_read, например { "path": "<path returned by vault_search>" }.

3. Предварительно просмотрите безопасную мутацию заметки перед её применением:

   {
     "name": "MCP smoke note",
     "content": "Created after reviewing the plan.",
     "dryRun": true
   }

   Это вызов note_create. Он возвращает запланированное действие и точную команду CLI без изменения хранилища. Используйте dryRun: false только после проверки плана. dryRun — это предварительный просмотр, а не граница авторизации.

4. Для Canvas предварительно просмотрите нативный файл Canvas и один текстовый узел:

   {
     "path": "MCP smoke.canvas",
     "nodes": [
       {
         "id": "hello",
         "type": "text",
         "x": 0,
         "y": 0,
         "width": 320,
         "height": 180,
         "text": "Hello from MCP"
       }
     ],
     "dryRun": true
   }

   Это вызов canvas_create. Изучите план, затем вызовите его с dryRun: false, если хотите создать файл. Используйте canvas_read для проверки нативного JSON .canvas после этого. Инструменты Canvas сохраняют неизвестные поля, проверяют ссылки на узлы/рёбра и не требуют произвольного eval.

Конфигурация и безопасные значения по умолчанию

Пустая или отсутствующая конфигурация пригодна для обычного хранилища Obsidian. Необязательный .obsidianmcprc.yaml обнаруживается в рабочем каталоге сервера. Для клиентов с непредсказуемым рабочим каталогом установите OBSIDIAN_MCP_CONFIG в явный путь к файлу конфигурации.

Политика по умолчанию намеренно локальная и ограниченная:

• Сервер v0.4.0 не предоставляет универсальный инструмент obsidian_eval. eval.enabled по умолчанию false; внутренние фиксированные фрагменты eval, используемые несколькими безопасными операциями, не являются предоставленным пользователем способом обхода JavaScript.

• Импорт из произвольных локальных файлов отключён, пока imports.allowedRoots не настроен явно. URL-адреса никогда не загружаются.

• Сегменты пути .obsidian, .git, .trash, .Trash, Trash и .DS_Store блокируются по умолчанию. Добавьте paths.allow для более узкой области хранилища и добавьте специфичные для проекта префиксы paths.deny для более чувствительного содержимого.

• Мутации предоставляют dryRun. file_delete требует confirm: true, а note_delete по умолчанию использует корзину Obsidian; постоянное удаление требует явной конфигурации delete.mode: hard.

• Автокоммит Git по умолчанию выключен.

Пресет только для чтения

Используйте явный список разрешений, когда MCP-клиент должен только просматривать хранилище:

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - file_read_binary_metadata
    - canvas_read

Безопасный локальный пресет

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

tools:
  allow:
    - vault_search
    - note_read
    - note_list
    - vault_tags
    - unresolved_links
    - tasks_list
    - note_diff
    - backlinks_get
    - outlinks_get
    - canvas_read
    - canvas_create
    - canvas_upsert_nodes
    - canvas_upsert_edges
    - canvas_add_node
    - canvas_add_edge
    - canvas_auto_layout
    - canvas_open
    - note_create
    - note_append
    - note_set_frontmatter
    - note_replace_range
    - note_insert_at
    - note_replace
    - note_insert
    - daily_open
    - daily_append
    - task_create
    - task_update
delete:
  mode: trash
eval:
  enabled: false
imports:
  allowedRoots: []

Полный доверенный локальный пресет

Опустите tools.allow, чтобы открыть полную встроенную поверхность инструментов, сохраняя защищённые пути по умолчанию, удаление в корзину, отключённый импорт и отключённый obsidian_eval. Если нужен импорт, настройте только выделенный локальный исходный каталог:

imports:
  allowedRoots:
    - /absolute/path/to/approved-imports
  maxBytes: 26214400
  collision: increment
delete:
  mode: trash
eval:
  enabled: false

См. docs/configuration.md для всех полей и examples/ для пресетов организации заметок.

Локальный stdio против удалённого HTTP

Локальный stdio запускает один процесс сервера непосредственно из MCP-клиента. Это рекомендуемая установка: нет слушающего сокета, удалённой аутентификации, настройки Cloudflare или публичной конечной точки.

Streamable HTTP — это дополнительный расширенный режим для клиента, который не может использовать локальный stdio. Он привязывается только к loopback и отказывается запускаться без проверки JWT Cloudflare Access или сильного токена возможностей. Поместите его за TLS, аутентифицированный обратный прокси или туннель; не привязывайте его к 0.0.0.0. См. docs/remote-cloudflare.md для общей расширенной настройки и её компромиссов безопасности.

Поверхность инструментов

Сервер по умолчанию предоставляет 42 обычных инструмента:

• Чтение: vault_search, note_read, note_list, vault_tags, unresolved_links, tasks_list, note_diff, backlinks_get, outlinks_get, file_read_binary_metadata, canvas_read.

• Запись и рабочий процесс: note_create, note_append, note_set_frontmatter, daily_open, daily_append, note_replace_range, note_insert_at, note_replace, note_insert, task_create, task_update, note_transition.

• Файлы и вложения: file_import, attachment_import, note_attach, attachment_embed, file_move, file_rename, file_delete, note_rename, note_move, folder_create, note_delete.

• Canvas: canvas_create, canvas_upsert_nodes, canvas_upsert_edges, canvas_remove, canvas_open, canvas_add_node, canvas_add_edge, canvas_auto_layout.

Все изменяющие инструменты принимают dryRun. Аннотации инструментов определяют операции только для чтения и разрушительные операции для совместимых MCP-клиентов.

Ограничения и безопасность

Obsidian Desktop должен быть запущен, его официальный CLI должен быть включён, а активное хранилище должно быть доступно этому сеансу рабочего стола. Этот сервер не является песочницей и не поддерживает obsidian-headless.

Содержимое хранилища — это недоверенные данные. Заметки, текст Canvas, текст задач и результаты поиска могут содержать инструкции по внедрению промптов; MCP-клиент должен обращаться с ними как с данными и никогда не следовать инструкциям, найденным в хранилище, только потому, что они были возвращены инструментом. Вывод инструментов также может содержать конфиденциальное содержимое хранилища, поэтому подключайте только те клиенты, которым вы доверяете.

Прочтите SECURITY.md перед включением удалённого HTTP, импорта, необратимого удаления или широкого списка разрешений на мутации. Сообщайте о проблемах безопасности конфиденциально, как описано там.

Разработка и CI

Исходный код использует Bun, а опубликованный bin работает на Node:

bun install
bun run typecheck
bun test
bun run build:schema
bun run build
bun run smoke:stdio
git diff --check
npm pack --dry-run --json

Офлайн-дымовой тест stdio проверяет точку входа собранного пакета, инициализацию MCP, tools/list, ожидаемую поверхность инструментов и отсутствие obsidian_eval. Настоящий дымовой тест Obsidian отдельный и требует пользовательского сеанса с запущенным Obsidian:

OBSIDIAN_CLI_BINARY=obsidian \
  OBSIDIAN_MCP_CONFIG=/absolute/path/to/your/config.yaml \
  OBSIDIAN_MCP_VAULT="your-vault-name" \
  bun run smoke:live

GitHub Actions запускает только офлайн-проверки; он не зависит от Obsidian Desktop или реального хранилища на размещённом раннере.

Лицензия

MIT