obsidian-mcp

MCP-сервер, который является оберткой для официального CLI Obsidian, позволяя агенту LLM управлять запущенным экземпляром Obsidian — читать/записывать заметки, искать, управлять метаданными, переходить по ссылкам, запускать плагины и многое другое.

Этот сервер представляет собой легкую и комплексную обертку. Каждый инструмент соответствует команде CLI obsidian в соотношении 1:1.

Предварительные требования

1. Obsidian должен быть запущен. CLI взаимодействует с работающим приложением через IPC; он не читает хранилище (vault) напрямую с диска.

2. Зарегистрируйте бинарный файл CLI. В Obsidian: Настройки → Общие → Интерфейс командной строки → Зарегистрировать CLI. Obsidian добавит obsidian в ваш PATH.

3. Проверка: obsidian version выводит версию CLI.

Установка

Два пути в зависимости от того, хотите ли вы собрать его самостоятельно или взять предварительно опубликованную версию из npm.

Вариант А — Клонирование и сборка (работает сейчас)

Клонируйте репозиторий и выполните сборку локально, затем укажите Claude Code путь к собранному файлу:

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

Зарегистрируйте его в Claude Code (одной командой):

# Add (user scope — available across all projects)
claude mcp add -s user obsidian -- node /absolute/path/to/obsidian-mcp/dist/index.js

# Remove
claude mcp remove obsidian

# List configured servers
claude mcp list

-s user регистрирует его для всей вашей учетной записи пользователя. Используйте -s project, чтобы зафиксировать его в файле .mcp.json репозитория, или -s local только для текущего проекта (по умолчанию).

Или добавьте его в .mcp.json вручную:

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

Вариант Б — Установка из npm (без сборки)

Предварительное требование: пакет уже должен быть опубликован в npm. Сопровождающий публикует его один раз через npm publish; все последующие пользователи получают его через npx автоматически. Если вы сделали форк этого репозитория и хотите использовать этот поток под своим именем, измените name в package.json на @<ваше-имя-пользователя-npm>/obsidian-mcp, затем выполните npm publish.

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

claude mcp add -s user obsidian -- npx -y @yuchichang/obsidian-mcp

Или в .mcp.json / claude_desktop_config.json для Claude Desktop:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@yuchichang/obsidian-mcp"]
    }
  }
}

Переопределение пути к CLI

Если obsidian отсутствует в PATH, установите переменную окружения OBSIDIAN_CLI. Работает с любым путем установки:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_CLI": "C:/Users/you/AppData/Local/Obsidian/obsidian.cmd"
      }
    }
  }
}

Инструменты

Хранилище и файлы

Свойства метаданных (Frontmatter)

Поиск

Теги и ссылки

Ежедневные заметки

Плагины

Разработчик / продвинутые функции

Мета

Соглашения

• Выбор заметки — инструменты, работающие с файлами, принимают либо:

  • file — имя заметки в стиле вики-ссылок (например, "My Note"), либо

  • path — путь к файлу относительно хранилища (например, "Folder/My Note.md").

• Настройка нескольких хранилищ — каждый инструмент принимает необязательный параметр vault. Если он опущен, используется последнее активное хранилище.

• Формат вывода — инструменты для списка/поиска/метаданных по умолчанию используют JSON для удобного машинного разбора.

Чувствительные операции и подтверждение пользователя

Следующие инструменты защищены этапом подтверждения пользователем:

Как работает защита:

1. Запрос MCP (предпочтительно). Если подключенный клиент поддерживает возможность elicitation (Claude Code поддерживает), сервер отправляет запрос elicitation/create, и клиент показывает пользователю запрос Продолжить? с описанием действия и цели. Только accept + confirm: true позволяет продолжить.

2. Явный параметр confirm: true. Схема ввода каждого чувствительного инструмента включает необязательный параметр confirm: boolean. Передача confirm: true пропускает запрос на подтверждение — используйте это только тогда, когда вызывающая сторона уже получила одобрение пользователя.

3. Отказ в качестве резервного варианта. Если клиент не поддерживает elicitation и параметр confirm: true не был предоставлен, инструмент возвращает результат isError, который называет действие и инструктирует вызывающую сторону повторить попытку с confirm: true.

Обход для пакетных операций / автоматизации

OBSIDIAN_MCP_AUTO_CONFIRM=1

Установите эту переменную окружения (в блоке env вашего MCP-клиента), чтобы пропускать каждый запрос на подтверждение. Используйте только в полностью доверенных контекстах автоматизации.

Длинный контент и ограничения аргументов

CLI Obsidian (пока) не поддерживает чтение значений параметров из stdin или файлов — каждое значение передается через командную строку. Это приводит к конфликту с ограничениями платформы:

Разбиение происходит по границам строк, когда это возможно; слишком длинные одиночные строки разбиваются по границам символов, безопасным для UTF-8. Собранный контент побайтово идентичен оригиналу.

Настройте пороговое значение байтов для каждого вызова (по умолчанию: 6,000 на Windows, 100,000 в других системах):

OBSIDIAN_MCP_MAX_ARG_BYTES=4000

Если часть в середине многочастной записи не удалась, сервер возвращает isError с четким сообщением о том, какие части были записаны на диск, чтобы вызывающая сторона могла восстановиться.

Разработка

npm run dev      # tsc --watch
npm run inspect  # launch MCP Inspector against the built server
node scripts/smoke-test.mjs   # initialize + tools/list smoke test

Как это работает

runObsidian() (src/exec.ts) заключает аргументы в кавычки для оболочки, вызывает бинарный файл obsidian через child_process.exec и разбирает stdout. Большинство инструментов для чтения запрашивают format=json; результаты разбираются в structuredContent для клиентов, которые потребляют структурированный вывод инструментов, при этом возвращая текстовое представление в content.

Реестр инструментов находится в src/tools.ts — добавление новой обертки для команды — это одна запись там.

Справочная информация

• CLI Obsidian: https://obsidian.md/help/cli

• Спецификация MCP: https://modelcontextprotocol.io