Локальный REST API с MCP

Дайте вашим скриптам, расширениям браузера и ИИ-агентам прямой доступ к вашему хранилищу Obsidian через безопасный REST API с аутентификацией.

• Интерактивная документация API: https://coddingtonbear.github.io/obsidian-local-rest-api/

• Страница сообщества Obsidian: https://community.obsidian.md/plugins/obsidian-local-rest-api/

• Что вы можете делать

• Быстрый старт

  • REST API

  • MCP-клиенты

    • Claude Code

    • Claude Desktop

    • Cursor

    • Другие клиенты

• Обзор API

• Примечания по патчингу

  • Режим raw-контента

• Нацеливание на конкретные разделы

• Поиск

• MCP (Model Context Protocol)

  • Версии протокола

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

  • Доступные инструменты

  • Доступные ресурсы

• Расширения API

  • Типизированный API расширений

  • Известные расширения

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

• Благодарности

Что вы можете делать

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

• Читать, создавать, обновлять или удалять заметки — полный CRUD для любого файла в вашем хранилище, включая бинарные файлы

• Хирургически патчить конкретные разделы — нацеливайтесь на заголовок, ссылку на блок или ключ frontmatter и добавляйте, вставляйте, заменяйте, удаляйте или перемещайте только этот раздел, не затрагивая остальную часть файла

• Искать в хранилище — простой полнотекстовый поиск или структурированные запросы JsonLogic по метаданным заметок (frontmatter, теги, путь, контент)

• Доступ к активному файлу — читайте или записывайте заметку, которая в данный момент открыта в Obsidian

• Список и выполнение команд — запускайте любую команду Obsidian, как если бы вы использовали палитру команд

• Запрос тегов — список всех тегов в вашем хранилище с количеством использований

• Открытие файлов в Obsidian — укажите Obsidian открыть конкретную заметку в его интерфейсе

• Расширение API — другие плагины могут регистрировать свои собственные маршруты через интерфейс расширения API

Все запросы обслуживаются по HTTPS с самозаверяющим сертификатом и защищены аутентификацией по API-ключу.

Related MCP server: Connect MCP

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

После установки и включения плагина откройте Настройки → Local REST API, чтобы найти ваш API-ключ и сертификат.

REST API

# Check the server is running (no auth required)
curl -k https://127.0.0.1:27124/

# List files at the root of your vault
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/

# Read a note
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md

# Read a specific heading (URL-embedded target)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append a line to a specific heading (PATCH with a JSON instruction)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["My Section"],"operation":"append","content":"New line of content"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

Чтобы избежать предупреждений о сертификате, вы можете скачать и довериться сертификату с https://127.0.0.1:27124/obsidian-local-rest-api.crt или указать на него вашему HTTP-клиенту напрямую.

MCP-клиенты

MCP-сервер работает по адресу https://127.0.0.1:27124/mcp/ и требует предоставления вашего bearer-токена для аутентификации через заголовок Authorization (т.е. Authorization: Bearer <your-api-key>). Поскольку плагин использует самозаверяющий сертификат, вам может потребоваться либо довериться сертификату в вашей ОС/клиенте, либо использовать обычный HTTP-эндпоинт по адресу http://127.0.0.1:27123/mcp/ (включите его в Настройки → Local REST API → Включить HTTP-сервер).

Claude Code

Claude Code имеет встроенную поддержку HTTP MCP. Самый быстрый способ добавить сервер — через CLI:

claude mcp add --transport http obsidian https://127.0.0.1:27124/mcp/ \
  --header "Authorization: Bearer <your-api-key>"

Или добавьте его вручную в .mcp.json в корне вашего проекта (в рамках проекта) или настройте его для пользователя через claude mcp add --scope user:

{
  "mcpServers": {
    "obsidian": {
      "type": "http",
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Claude Desktop

Claude Desktop не поддерживает удалённые HTTP MCP-серверы нативно, но вы можете соединить его с помощью mcp-remote (требуется Node.js). Добавьте следующее в claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://127.0.0.1:27124/mcp/",
        "--header",
        "Authorization: Bearer <your-api-key>"
      ]
    }
  }
}

Перезапустите Claude Desktop после сохранения файла.

Cursor

Cursor поддерживает транспорт Streamable HTTP MCP. Добавьте следующее в ~/.cursor/mcp.json (глобально) или .cursor/mcp.json (для проекта):

{
  "mcpServers": {
    "obsidian": {
      "url": "https://127.0.0.1:27124/mcp/",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Другие клиенты

Любой MCP-клиент, поддерживающий транспорт Streamable HTTP, может подключиться к https://127.0.0.1:27124/mcp/ с заголовком Authorization: Bearer <your-api-key>. Обратитесь к документации вашего клиента за точным форматом конфигурации.

Обзор API

Полные детали запросов/ответов см. в интерактивной документации.

Примечания по патчингу

Метод PATCH — одна из самых полезных функций этого API. Он позволяет вносить точечные изменения без переписывания целых файлов.

Отправьте JSON-инструкцию: операцию (replace, prepend, append или delete), применяемую к области (content, marker, markerAndContent или parent) цели — заголовка (адресуемого как массив текстов заголовков сверху вниз), ссылки на блок или ключа frontmatter. Полезная нагрузка передаётся в content (строка), value (JSON, для значений frontmatter) или destination (перемещение заголовка):

# Replace the value of a frontmatter field
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"frontmatter","target":"status","operation":"replace","value":"done"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

Уровни заголовков внутри строки content относительны цели (ведущий # становится прямым дочерним элементом). Предупреждения (например, заголовок, перенесённый за уровень 6) возвращаются в виде процентно-кодированного JSON в заголовке ответа Markdown-Patch-Warnings — декодируйте с помощью decodeURIComponent перед разбором. Передайте ifMatch (значение version из карты документа) для оптимистичной конкурентности.

Примечание: Пробелы принадлежат библиотеке — ваш контент приводится к обрезанной канонической форме (ведущие и завершающие пустые строки не имеют значения), и сам API добавляет пустую строку там, где вставленный контент граничит с текстом, так что append или prepend всегда попадает в отдельный блок и никогда не сливается с существующим абзацем. Строки заголовков, существующие пустые строки и стиль интервалов каждого документа сохраняются как есть. Примеры см. в интерактивной документации.

Чтобы продолжить существующий блок вместо создания нового — например, расширить список — добавьте within к инструкции заголовка: индекс, выбирающий один из верхнеуровневых блоков тела секции (с нуля в порядке документа, отрицательные считаются с конца, так что -1 — последний блок). Редактирование с within вставляет буквально, так что вы контролируете стык:

# Add an item to the last list under "Log" (the leading \n continues the block)
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  --data '{"targetType":"heading","target":["Log"],"within":-1,"operation":"append","content":"\n- new item"}' \
  https://127.0.0.1:27124/vault/path/to/note.md

С областью markerAndContent операции prepend/append вместо этого вставляют новый блок рядом с указанным. Индексы позиционны, поэтому сначала прочитайте карту документа и сочетайте редактирование с ifMatch.

Режим raw-контента

Если ваш клиент шаблонизирует markdown в теле запроса (Shortcuts, Tasker, curl из шаблона), JSON-экранирование этого контента в инструкции ненадёжно. Режим raw-контента выносит поля инструкции из тела — цель в URL (или в заголовках Target-Type/Target с явным Markdown-Patch-Version: 2), операцию и параметры в заголовки — а тело является необработанной полезной нагрузкой, без необходимости JSON-экранирования:

# Append a templated line under a heading — no JSON escaping anywhere
curl -k -X PATCH \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Operation: append" \
  -H "Content-Type: text/markdown" \
  --data "- $TEMPLATED_CONTENT" \
  https://127.0.0.1:27124/vault/notes/daily.md/heading/Log

Тело text/* является носителем content, тело application/json — носителем value, а отсутствие тела вообще ничего не несёт (delete или перемещение через заголовок Destination). Заголовки Target-Scope, Within (индекс within инструкции как простое целое число, например -1), Create-Target-If-Missing, Reject-If-Content-Preexists и If-Match дополняют инструкцию. См. интерактивную документацию для кодировок заголовков и полных деталей.

Уже используете старый формат PATCH на основе заголовков? Он распределял инструкцию по заголовкам запроса вместо JSON-тела и устарел и будет удалён в 6.0. Он всё ещё работает — отправьте Markdown-Patch-Version: 1, чтобы вернуться к нему (тот же заголовок также выбирает устаревшую карту документа с разделителем :: при GET), и ответы, обслуживаемые им, содержат заголовок Deprecation: true; sunset-version="6.0". Для обновления удалите этот заголовок и перенесите каждый заголовок в JSON-тело; в интерактивной документации есть таблица соответствия полей.

Полную схему инструкции и параметры см. в интерактивной документации.

Нацеливание на конкретные разделы

Вы можете читать или записывать конкретную часть заметки — заголовок, ссылку на блок или поле frontmatter — без получения или замены всего файла. Это работает для запросов GET, PUT, POST и PATCH (для PATCH это режим raw-контента — добавьте заголовок Operation).

Добавьте /<target-type>/<target> после имени файла. Каждый вложенный уровень заголовка является отдельным сегментом пути, поэтому заголовок, текст которого содержит ::, не требует экранирования:

# Read the content under a specific heading
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Read a nested heading (one path segment per level)
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/Work/Meetings

# Read a frontmatter field
curl -k -H "Authorization: Bearer <your-api-key>" \
  https://127.0.0.1:27124/vault/path/to/note.md/frontmatter/status

# Replace the content of a heading via PUT (heading levels are normalized for you)
curl -k -X PUT \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Updated content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

# Append to a heading via POST
curl -k -X POST \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: text/markdown" \
  --data "Appended content" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

Поддерживаемые типы целей: heading, block, frontmatter.

При GET заголовок Target-Scope выбирает, какая часть цели возвращается, повторяя области PATCH: content (по умолчанию), marker (метка — необработанный текст заголовка, голый идентификатор блока, ключ frontmatter) или markerAndContent (весь узел, в точности в той форме, которую потребляет PATCH replace в этой области — поддерево заголовка читается со своей строкой как # Title, уровни относительны его родителю):

# Read a whole section — heading line included — ready to edit and write back
curl -k -H "Authorization: Bearer <your-api-key>" \
  -H "Target-Scope: markerAndContent" \
  https://127.0.0.1:27124/vault/path/to/note.md/heading/My%20Section

Устарело: нацеливание на основе заголовков. В более ранних версиях раздел нацеливался с помощью заголовков Target-Type, Target и Target-Delimiter (плюс Target-Scope/Trim-Target-Whitespace). Эта форма устарела и будет удалена в 6.0; она обрабатывается только при отправке Markdown-Patch-Version: 1 (тогда ответы содержат заголовок Deprecation). Без него предоставление этих заголовков нацеливания отклоняется с 400. Предоставление и URL-пути нацеливания, и формы заголовков в одном запросе возвращает 422 Unprocessable Entity.

Поиск

POST /search/simple/?query=your+terms запускает встроенный нечёткий поиск Obsidian и возвращает соответствующие имена файлов с оценёнными фрагментами контекста.

POST /search/ принимает выражение JsonLogic (тип контента application/vnd.olrapi.jsonlogic+json) и вычисляет его для метаданных каждой заметки (frontmatter, теги, путь, контент).

MCP (Model Context Protocol)

[!NOTE] Для Obsidian существует несколько сторонних MCP-серверов, но они больше не нужны — этот плагин поставляется со встроенным MCP-сервером, который работает внутри Obsidian и имеет прямой доступ к живым метаданным вашего хранилища, активному файлу и палитре команд. Если вы сейчас используете сторонний сервер, переход на этот, скорее всего, даст вам лучшие результаты.

Плагин включает встроенный MCP-сервер по адресу /mcp/, чтобы ИИ-агенты и MCP-совместимые клиенты могли взаимодействовать с вашим хранилищем без ручного составления HTTP-запросов.

Транспорт: Streamable HTTP — требуется аутентификация по API-ключу.

Версии протокола

Конечная точка обслуживает ревизию 2026-07-28, а также сессионные ревизии с 2024-10-07 по 2025-11-25, выбирая их для каждого запроса, так что клиенты на любой из них могут использовать её совместно.

Ревизия 2026-07-28 не сохраняет состояние: в ней нет рукопожатия initialize и нет сессии, поэтому плагин не выдаёт и не читает заголовок Mcp-Session-Id. Каждый запрос несёт собственную версию протокола и идентичность клиента в params._meta, повторяет их в заголовках MCP-Protocol-Version, Mcp-Method и Mcp-Name и обрабатывается независимо. Клиенты могут вызвать server/discover, чтобы заранее узнать поддерживаемые ревизии и возможности.

Клиенты, которые начинают с запроса initialize, обслуживаются той сессионной ревизией, которую они согласовали: рукопожатие возвращает Mcp-Session-Id, GET /mcp/ открывает поток уведомлений этой сессии, а DELETE /mcp/ завершает её. Сессии существуют только на этом пути, и именно они обеспечивают честность возможностей listChanged из рукопожатия: когда другой плагин регистрирует или удаляет MCP-инструмент, уведомляется каждая активная сессия, а клиенты 2026-07-28 узнают об этом через поток subscriptions/listen.

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

Подключите ваш MCP-клиент к https://127.0.0.1:27124/mcp/. Аутентификация использует bearer-токен — найдите свой API-ключ в Настройки → Local REST API, затем передайте его так:

Authorization: Bearer <your-api-key>

Точный синтаксис конфигурации зависит от клиента; см. примеры в разделе Быстрый старт выше или обратитесь к документации вашего клиента по удалённым MCP-серверам Streamable HTTP.

[!WARNING] Для безопасного подключения к MCP-серверу ваш клиент должен доверять самоподписанному сертификату плагина. Вы можете скачать его и добавить в доверенные с https://127.0.0.1:27124/obsidian-local-rest-api.crt, либо настроить клиент на пропуск проверки TLS для 127.0.0.1.

Если доверие к самоподписанному сертификату невозможно в вашем окружении, вы можете подключиться небезопасно через http://127.0.0.1:27123/mcp/ вместо https://127.0.0.1:27124/mcp/, если вы включили HTTP-конечную точку в Настройки → Local REST API → Enable HTTP server.

Доступные инструменты

Доступные ресурсы

Расширения API

Другие плагины могут регистрировать свои собственные аутентифицированные маршруты, публичные маршруты и MCP-инструменты на сервере этого плагина. См. пошаговое руководство в разделе Adding your own API Routes via an Extension.

Типизированное расширение API

Установите этот пакет как зависимость для разработки, чтобы получить getAPI и типы для всего, что он возвращает:

npm install --save-dev obsidian-local-rest-api

Этот пакет объявляет obsidian, zod и @types/express как peer-зависимости, потому что его типы ссылаются на все три — addRoute возвращает IRoute от express, а addMcpTool принимает схемы zod. npm устанавливает peer-зависимости за вас; если вы закрепляете их сами, следите, чтобы они оставались разрешимыми. Без них TypeScript молча расширяет эти позиции до any вместо сообщения об ошибке, поэтому проект, подавляющий диагностику отсутствующих типов, не получает предупреждения о том, что потерял проверку типов именно там, где это важнее всего.

import { getAPI, type LocalRestApiPublicApi } from "obsidian-local-rest-api";

const api: LocalRestApiPublicApi | undefined = getAPI(this.app, this.manifest, 2);

Точка входа пакета — это небольшой автономный модуль: он извлекает работающий хост-плагин из реестра плагинов Obsidian, а не тянет бандл плагина в вашу сборку. Передача версии API расширения (2 выше) заставляет getAPI выбрасывать ApiVersionUnsupportedError, когда установленный хост старше той поверхности, которая вам нужна; опустите её, чтобы принимать любую установленную версию и определять возможности самостоятельно. getAPI возвращает undefined, если плагин не установлен или ещё не загружен.

publicApi.d.ts генерируется из src/publicApi.ts, с которым реализация проверяется на этапе компиляции, поэтому опубликованные типы не могут разойтись с тем, что плагин реально предлагает.

Известные расширения

• Periodic Notes: добавляет поддержку периодических заметок

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

См. CONTRIBUTING.md. Если вы хотите добавить функциональность без изменения ядра, рассмотрите возможность создания расширения API — расширения можно разрабатывать и выпускать независимо.

Благодарности

Вдохновлено плагином advanced-uri от Vinzent03 с целью расширить возможности автоматизации за пределы ограничений пользовательских URL-схем.