obsidian-mcp-server

[!NOTE] Этот репозиторий — huaqing0 custom edition, основанный на cyanheads/obsidian-mcp-server v3.5.0 под лицензией Apache-2.0. Он сохраняет вышестоящий сервер и добавляет локальное рабочее пространство, структуру хранилища и нативную автоматизацию Excalidraw, используемые в этой редакции. Ссылки для установки npm и MCPB ниже по-прежнему указывают на вышестоящий дистрибутив; эта кастомная редакция пока доступна только в виде исходного кода.

Инструменты

Тридцать один инструмент охватывает содержимое заметок, метаданные, обратные ссылки, нативную автоматизацию Excalidraw и полное управление структурой хранилища, а также защищённый аварийный выход для команд палитры команд Obsidian.

obsidian_get_note

Читает заметку в одной из четырёх проекций, адресуемых по пути в хранилище, активному файлу или периодической заметке (daily, weekly, monthly, quarterly, yearly).

• format: "content" — необработанное тело Markdown

• format: "full" — содержимое, frontmatter, теги и метаданные файла; передайте includeLinks: true, чтобы включить записанные исходящие ссылки плюс разрешённые Obsidian исходящие ссылки и обратные ссылки (только внутренние для хранилища — внешние URL отфильтровываются)

• format: "document-map" — каталог заголовков, ссылок на блоки и полей frontmatter

• format: "section" — значение одного раздела заголовка/блока/frontmatter (требуется section); разделы заголовков включают полное поддерево под этим заголовком

Сочетайте проекцию document-map с obsidian_patch_note, чтобы обнаруживать цели редактирования перед внесением изменений.

obsidian_search_notes

До трёх режимов поиска, выбираемых через mode:

• text — поиск подстроки с окружающими окнами контекста. contextLength управляет количеством символов контекста с каждой стороны каждого совпадения (по умолчанию 100; увеличьте для большего контекста на совпадение). Опциональный фильтр pathPrefix (только для текстового режима — передача pathPrefix в любом другом режиме отклоняется с path_prefix_invalid_mode).

• jsonlogic — дерево JSONLogic, вычисляемое по path, content, frontmatter.<key>, tags и stat.{ctime,mtime,size}; пользовательские операторы glob и regexp, оба принимающие [PATTERN, VALUE] — сначала шаблон, затем ссылка на поле: {"glob": ["Projects/*.md", {"var": "path"}]}. Обратный порядок компилирует собственное поле заметки как шаблон: тогда glob не находит ничего, а regexp сразу же завершается ошибкой на том, во что разбирается поле. Так же выражаются обратные ссылки, поскольку для них нет отдельного инструмента или вышестоящей конечной точки: {"regexp": ["\\[\\[Target Note(\\||#|\\]\\])", {"var": "content"}]} возвращает каждую заметку, в теле которой есть вики-ссылка на Target Note.

• omnisearch — поиск с ранжированием BM25 через плагин сообщества Omnisearch. Поддерживает фразы в кавычках, -exclusion, фильтры path: / ext:, устойчивость к опечаткам, покрытие PDF + OCR (через Text Extractor) и совпадения изображений по визуальной концепции, когда включена индексация AI Image Analyzer. Присутствует в перечислении режимов только когда HTTP-сервер плагина доступен при запуске; вышестоящий сервис жёстко ограничивает результаты 50 — сузьте запрос, чтобы показать больше (ответ содержит truncated: true, когда предел, вероятно, был достигнут).

Результаты разбиваются на страницы с помощью непрозрачных курсоров в соответствии со спецификацией MCP от 2025-11-25: опустите cursor для первой страницы, затем передайте nextCursor из предыдущего ответа. Каждый результат содержит totalCount (после применения политики путей, до разбиения на страницы); nextCursor опускается на последней странице. Совпадения в текстовом режиме дополнительно обрезаются по файлу в соответствии с maxMatchesPerHit (по умолчанию 10), чтобы одна заметка с большим количеством совпадений не превысила бюджет ответа — обрезанные совпадения имеют truncated: true и totalMatches.

obsidian_write_note

Создание или хирургическая замена с защитным поведением по умолчанию против случайной перезаписи всего файла.

• Без section — полный PUT файла. Отказывается затирать существующий файл, если не установлен overwrite: true. Ошибка file_exists (Conflict) предлагает obsidian_patch_note / obsidian_append_to_note / obsidian_replace_in_note для правок на месте.

• С section — PATCH-с-заменой по указанному заголовку/блоку/полю frontmatter, оставляя остальную часть файла нетронутой. Флаг overwrite игнорируется в режиме section.

В выводе сообщается created: true, когда вызов создал новый файл; false, когда он заменил существующий или был нацелен на секцию. Каждый изменяющий инструмент также возвращает previousSizeInBytes и currentSizeInBytes, чтобы агент мог заметить случайные затирания, неожиданное поведение вышестоящей системы или опечатку в пути, которая привела к не тому файлу.

obsidian_append_to_note

Комбинированный примитив upsert + добавление к секции, повторяющий поведение вышестоящего Local REST API:

• Без section — POST к /vault/{path}. Добавляет, если файл существует, создаёт файл с вашим содержимым в качестве всего тела, если его нет. В выводе created: true помечает вторую ветку, чтобы агент мог заметить, когда опечатка в пути или ещё не созданная ежедневная заметка незаметно превратилась в новый файл.

• С section — PATCH-с-добавлением по указанному заголовку, ссылке на блок или полю frontmatter. Файл должен существовать (иначе предварительная проверка PATCH выбрасывает note_missing). Передайте createTargetIfMissing: true, чтобы создать саму секцию внутри существующего файла. Цели-ссылки на блоки объединяются смежно со строкой блока без разделителя — включите ведущий символ новой строки в content, если он нужен.

previousSizeInBytes равен 0 в ветке создания upsert и фактическому размеру файла в противном случае; currentSizeInBytes — размер после записи, считанный из вышестоящей системы после операции. Сравните дельты с Buffer.byteLength(content), чтобы обнаружить автоматическую вставку новой строки или параллельных писателей.

obsidian_patch_note

Хирургические правки по одной цели документа.

• operation: "append" добавляет после секции

• operation: "prepend" добавляет перед секцией

• operation: "replace" заменяет её

• Цели: путь заголовка, ID ссылки на блок или поле frontmatter

Цели-заголовки принимают либо полный путь Parent::Child, либо простое имя листа. Простое имя, совпадающее ровно с одним заголовком, разворачивается в полный путь перед записью, и ответ возвращает локатор, на который пришлась правка; имя, совпадающее с несколькими заголовками, отклоняется с ambiguous_section, данные ошибки которого перечисляют пути-кандидаты. Та же логика разрешения применяется к obsidian_write_note и obsidian_append_to_note с section.

Используйте obsidian_get_note с format: "document-map", чтобы узнать, какие цели существуют перед патчем.

obsidian_replace_in_note

Поиск-и-замена для правок, которые не подходят под структурные цели obsidian_patch_note. Заметка извлекается, замены применяются последовательно (каждая видит предыдущий вывод), и результат записывается обратно одним PUT.

scope выбирает, по чему выполняются замены:

• body (по умолчанию) — текст после блока YAML frontmatter. Блок повторно прикрепляется из исходных байтов, поэтому возвращается побайтово идентичным.

• frontmatter — только YAML между разделителями ---. Сами разделители никогда не сопоставляются.

• both — каждая замена выполняется по frontmatter, а затем по телу; perReplacement[] сообщает bodyCount и frontmatterCount отдельно.

Когда в область действия попадает frontmatter, переписанный YAML повторно разбирается перед любой записью: если он больше не разбирается как отображение свойств, вызов завершается с frontmatter_invalid, и заметка сохраняет исходные байты. Эта проверка ловит YAML, который ломается — незакавыченное : в скаляре, маркер списка, переписанный в алиас, случайная кавычка. Она не может поймать правку, которая остаётся корректной, но означает другое, например коллизию подстроки, переименовывающую ключ, или замену, снимающую кавычки со скаляра и меняющую его тип. Для типизированных правок одного свойства предпочитайте obsidian_manage_frontmatter.

Параметры для каждой замены:

• useRegex — трактовать search как регулярное выражение ECMAScript. При useRegex: true замена учитывает ссылки на группы захвата $1 / $&.

• caseSensitive — при false сопоставление без учёта регистра

• wholeWord — оборачивает шаблон в \b…\b; работает и в литеральном, и в regex-режиме

• flexibleWhitespace — заменяет любую последовательность пробелов в search на \s+. Только литеральный режим — не действует при useRegex: true (выразите это напрямую).

• replaceAll — при false заменяется только первое совпадение. При scope: 'both' эта одна замена идёт во frontmatter, если совпадение там, и в тело в противном случае.

Литеральный режим сохраняет $1 / $& в замене как есть — только useRegex: true разворачивает ссылки на группы захвата.

obsidian_manage_tags

Добавление, удаление или перечисление тегов заметки. Работает с одним из двух представлений, по умолчанию — с каноническим расположением frontmatter в Obsidian:

• location: 'frontmatter' (по умолчанию) — только массив tags: во frontmatter; тело заметки не трогается

• location: 'inline' — только встроенный синтаксис #tag в теле; add добавляет #tag в конец файла

• location: 'both' — согласование по выбору между обоими представлениями

add гарантирует наличие тега в запрошенном(ых) месте(ах); remove удаляет его; list игнорирует входной массив tags. Встроенные вхождения #tag внутри блоков кода в ограждениях намеренно не трогаются.

Встроенный режим читает и пишет только тело заметки — # внутри YAML-скаляра относится к frontmatter, поэтому он не перечисляется как встроенный тег и не переписывается при удалении. Удаление встроенного тега забирает с собой ровно один соседний горизонтальный пробел — тот, что перед тегом, или тот, что после, если перед ним пробела нет; каждый остальной байт сохраняется, включая отступы вложенных списков, блоки кода с отступом в четыре пробела, жёсткие переносы строк из двух пробелов в конце и отступы ячеек таблиц.

obsidian_delete_note

Окончательное удаление заметки. По умолчанию выключено. Установите OBSIDIAN_ENABLE_DELETE=true, чтобы открыть его в tools/list. Первый вызов отвечает запросом подтверждения, а не удалением — в подсказке указан размер файла в байтах, так что разрушительный радиус действия виден до подтверждения пользователем — и инструмент повторяется с ответом. Отказ или отмена завершают вызов с cancelled и не выполняют DELETE; аннотация destructiveHint также выводит операцию в поток одобрения хоста. В выводе сообщается previousSizeInBytes (размер на момент удаления) и currentSizeInBytes: 0.

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

Инструменты структуры хранилища

obsidian_create_folder идемпотентно создаёт вложенные папки. obsidian_move_path перемещает или переименовывает файлы или папки через собственный FileManager Obsidian, создавая недостающие родительские папки и позволяя Obsidian обновлять внутренние ссылки. obsidian_delete_folder рекурсивно удаляет папку, используя по умолчанию настроенное поведение корзины Obsidian, или окончательное удаление при явном запросе; он ограничен OBSIDIAN_ENABLE_DELETE=true вместе с удалением заметок.

obsidian_execute_command

Отправка команды из палитры команд Obsidian по ID (обнаруживается через obsidian_list_commands). Поведение зависит от команды — некоторые открывают интерфейс, другие удаляют файлы или закрывают хранилище.

По умолчанию выключено. Когда OBSIDIAN_ENABLE_COMMANDS не установлен, и obsidian_execute_command, и его партнёр по обнаружению obsidian_list_commands оборачиваются в disabledTool() — отсутствуют в tools/list (LLM не может их вызвать), но всё ещё видны в манифесте для оператора с подсказкой включить их.

Related MCP server: Obsidian Tools MCP Server

Политика путей (разрешения на уровне папок)

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

Сопоставление основано на префиксе с неявной рекурсией, без учёта регистра, с нормализацией завершающих слэшей. projects/ соответствует projects/a.md, projects/sub/b.md и т.д.

Пути записи неявно читаемы — нельзя разумно редактировать то, чего не видишь. Поэтому чтение проходит, когда цель соответствует READ_PATHS или WRITE_PATHS.

OBSIDIAN_READ_ONLY=true срабатывает до проверок путей — каждый инструмент записи и пара палитры команд оборачиваются в disabledTool() при запуске (отсутствуют в tools/list), и любая запись, которая всё же достигает сервиса, отклоняется во время выполнения независимо от WRITE_PATHS.

Отказы типизированы как path_forbidden (код JSON-RPC Forbidden) с активной областью действия, отражённой в data.recovery.hint и data.activeScope, чтобы LLM мог сам исправиться без просмотра журналов сервера. Результаты поиска из obsidian_search_notes фильтруются по READ_PATHS молча — показ индикатора «мы скрыли N совпадений» разрушил бы защиту.

Перечисление тегов действует на всё хранилище. obsidian_list_tags и ресурс obsidian://tags агрегируют имена тегов по всему хранилищу и не сужаются OBSIDIAN_READ_PATHS — у них нет пути для ограничения, поэтому имена тегов (но никогда содержимое заметок) из-за пределов области чтения могут всплывать.

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

Ресурсы

Все данные ресурсов также доступны через инструменты — obsidian_get_note для obsidian://vault/{+path}, obsidian_list_tags для obsidian://tags. Ресурсы существуют для клиентов, которые предпочитают прикреплять конкретную заметку или снимок хранилища к разговору. Пара тегов не является зеркалом: obsidian://tags сохраняет семантику снимка и возвращает вышестоящий полезный груз целиком и без сортировки, тогда как obsidian_list_tags упорядочивает по количеству и ограничивает.

Возможности

Построено на @cyanheads/mcp-ts-core:

• Декларативные определения инструментов и ресурсов — один файл на примитив, фреймворк берёт на себя регистрацию и валидацию

• Единая обработка ошибок — обработчики выбрасывают исключения, фреймворк перехватывает, классифицирует и форматирует их. Инструменты объявляют свою поверхность сбоев через типизированные контракты errors[].

• Серверные instructions при initialize — предоставляет специфичную для развёртывания ориентацию (политика активных путей, режим только для чтения, переключатель командной палитры) клиентам, совместимым со спецификацией, вместе со статическим каталогом инструментов и ресурсов

• Подключаемая аутентификация на HTTP-транспорте: none, jwt, oauth

• Структурированное логирование с опциональной трассировкой OpenTelemetry

• Транспорты STDIO и Streamable HTTP

Сам сервер не хранит состояние — каждый вызов инструмента обращается напрямую к Local REST API. Бэкенды хранилища фреймворка, KV для состояния запросов и потоки прогресса здесь не используются; Obsidian — это единое хранилище, и между вызовами нечего сохранять.

Специфично для Obsidian:

• Обёртка над плагином Obsidian Local REST API — типизированный клиент, детерминированное сопоставление ошибок

• Редактирование с учётом секций: заголовки, блочные ссылки и поля frontmatter через операции PATCH-с-целью

• Согласование тегов в обоих представлениях: массив tags: во frontmatter и инлайн-синтаксис #tag (с пропуском блоков кода в ограждениях)

• Поиск в трёх режимах: текстовый, JSONLogic и (когда плагин доступен) Omnisearch с ранжированием BM25 — курсорная пагинация по спецификации MCP 2025-11-25, с обрезкой совпадений по файлам в текстовом режиме

• Обязательное подтверждение человеком для разрушительных удалений — многораундовый запрос input_required на обеих версиях протокола, без неподтверждённого пути через инструмент

• Нативное управление структурой хранилища: создание папок, перемещение/переименование файлов или папок с обновлением ссылок Obsidian, удаление папок через корзину или безвозвратно

• Нативная интеграция с Excalidraw Automation API: семантические create/read/add/update/delete, детерминированная раскладка, проверка целостности, экспорт PNG-превью и идемпотентное встраивание заметок

• Права чтения/записи с ограничением по папкам через OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS и глобальный предохранитель OBSIDIAN_READ_ONLY — отказы типизированы как path_forbidden, активная область возвращается в данных ошибки

• Опциональная пара командной палитры (obsidian_list_commands + obsidian_execute_command) — регистрируется только при OBSIDIAN_ENABLE_COMMANDS=true

• Лояльное разрешение путей в obsidian_get_note и obsidian_open_in_ui — при несовпадении регистра тихо повторяет попытку с каноническим именем файла, выбрасывает Conflict при неоднозначных совпадениях по регистру и обогащает NotFound подсказками Did you mean: …?, когда есть только близкие совпадения. obsidian_delete_note намеренно исключён — разрушительная операция не должна молча переписывать целевой путь.

Начало работы

Добавьте следующее в файл конфигурации вашего MCP-клиента. Плагин Obsidian Local REST API должен быть установлен и включён в вашем хранилище — см. Предварительные требования.

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

Или через npx (Bun не требуется):

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

Для Streamable HTTP установите транспорт и запустите сервер. Инлайн-переменные окружения подходят для разовых запусков; для регулярного использования скопируйте значения в .env (см. .env.example) и выполните bun run start:http.

MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
# Server listens at http://127.0.0.1:3010/mcp by default

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

• Bun v1.3.0 или выше (или Node.js v24+).

• Плагин Obsidian Local REST API, версии 4.0.0–5.x, установленный и включённый в вашем хранилище. Сгенерируйте API-ключ в Настройки → Сторонние плагины → Local REST API и скопируйте его в OBSIDIAN_API_KEY. Плагин v6.0 удаляет wire-формат markdown-patch 1.x, на который этот сервер опирается для записи в секции и карты документов.

• Цели периодических заметок (target: { "type": "periodic" }) дополнительно требуют плагин v5.0.1 или более раннюю — в v5.0.2 удалены встроенные маршруты /periodic/. Все остальные типы целей не затронуты.

• MCP-клиент, умеющий отвечать на запрос ввода (elicitation). obsidian_delete_note всегда запрашивает подтверждение перед удалением, поэтому клиент без такой поддержки может читать и записывать заметки, но не может удалять.

• Опционально: плагин Obsidian Excalidraw установлен и включён для использования одиннадцати инструментов рисования. Остальные инструменты заметок и хранилища его не требуют.

• Этот сервер по умолчанию использует http://127.0.0.1:27123 для простоты. Включите «Non-encrypted (HTTP) Server» в настройках плагина, чтобы использовать его. Чтобы использовать всегда включённый HTTPS-порт, задайте OBSIDIAN_BASE_URL=https://127.0.0.1:27124; самоподписанный сертификат плагина обрабатывается через OBSIDIAN_VERIFY_SSL=false (по умолчанию).

Установка

1. Клонируйте репозиторий:

   git clone https://github.com/cyanheads/obsidian-mcp-server.git

2. Перейдите в каталог:

   cd obsidian-mcp-server

3. Установите зависимости:

   bun install

4. Настройте окружение:

   cp .env.example .env
   # edit .env and set OBSIDIAN_API_KEY

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

Полный список необязательных переопределений см. в .env.example.

Запуск сервера

Локальная разработка

• Сборка и запуск production-версии:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

• Запуск проверок и тестов:

bun run devcheck   # Lint, format, typecheck, security, changelog sync
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t obsidian-mcp-server .
docker run --rm -e OBSIDIAN_API_KEY=your-key -p 3010:3010 obsidian-mcp-server

Dockerfile по умолчанию использует HTTP-транспорт, режим сеансов без состояния и журналирование в /var/log/obsidian-mcp-server. Зависимости OpenTelemetry peer устанавливаются по умолчанию — соберите с --build-arg OTEL_ENABLED=false, чтобы исключить их.

Образ привязывается к 0.0.0.0 внутри контейнера (требуется для проброса портов Docker). Для любого развёртывания, доступного за пределами вашей машины, задайте MCP_AUTH_MODE=jwt (с MCP_AUTH_SECRET_KEY) или oauth — иначе слушатель будет передавать ваш OBSIDIAN_API_KEY хранилищу от имени любого вызывающего.

Структура проекта

Руководство по разработке

Руководство по разработке и архитектурные правила — в CLAUDE.md. Краткая версия:

• Обработчики выбрасывают исключения, фреймворк их ловит — никаких try/catch в логике инструментов

• Используйте ctx.log для логирования в рамках запроса, ctx.state — для хранилища в рамках тенанта

• Регистрируйте новые инструменты и ресурсы через barrel-файлы в src/mcp-server/*/definitions/index.ts

• Оборачивайте внешние вызовы API: валидируйте сырые данные → нормализуйте в доменный тип → возвращайте выходную схему; никогда не выдумывайте отсутствующие поля

Участие в разработке

Ошибки, запросы функций и пробелы в документации оформляются в виде issue — см. CONTRIBUTING.md о том, что делает issue полезным, и CODE_OF_CONDUCT.md о том, как мы работаем вместе. Сообщения о безопасности отправляются через SECURITY.md, никогда — в публичное issue.

Pull request'ы приветствуются для небольших самодостаточных исправлений. Перед отправкой запустите проверки и тесты:

bun run devcheck
bun run test

Лицензия

Apache-2.0 — подробности в LICENSE.