obsidian-mcp (Python)

Сервер MCP (Model Context Protocol) на Python, предоставляющий LLM-клиенту (например, Claude Desktop) доступ на чтение и запись к локальным хранилищам Obsidian через прямой доступ к файловой системе — без плагина Obsidian Local REST API, без HTTP и без токена авторизации.

Это Python-порт obsidian-mcp (TypeScript), функционально эквивалентный оригиналу, с несколькими намеренными исправлениями и упрощениями — полное обоснование см. в Plans/review-the-typescript-obsidian-mcp-parsed-shamir.md и ISA.md.

Предупреждение: этот сервер имеет доступ на чтение и запись к вашему хранилищу. Перед использованием сделайте резервную копию заметок (например, через git).

Требования

• Python 3.11+

• uv

• Хранилище Obsidian (каталог, открывавшийся в Obsidian хотя бы один раз, то есть содержащий .obsidian/app.json)

• macOS или Linux (Windows не поддерживается — см. ISA «Out of Scope»)

Related MCP server: Obsidian MCP Server

Установка и запуск

uv sync
uv run obsidian-mcp /path/to/your/vault [/path/to/another/vault ...]

Имена хранилищ автоматически образуются из базового имени каждого каталога (приводятся к нижнему регистру, небуквенно-цифровые символы заменяются на дефисы, дубликаты получают числовой суффикс). Максимум 10 хранилищ; пути хранилищ не должны быть вложены друг в друга.

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

Отредактируйте claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/py-obsidian-mcp", "obsidian-mcp", "/path/to/your/vault"]
    }
  }
}

Инструменты

read-note, create-note, edit-note (добавление в конец/в начало/замена/удаление), delete-note (по умолчанию мягкое удаление в .trash/), move-note, create-directory, search-vault (поиск по содержимому/имени файла/тегам с необязательным параметром max_results), add-tags, remove-tags, rename-tag (по всему хранилищу, с сохранением иерархии), list-available-vaults.

Также предоставляет ресурсную схему obsidian-vault:// (список/информация о хранилищах) и промпт list-vaults.

Разработка

uv sync --all-extras
uv run pytest -q
uv run ruff check src tests

Примечания по безопасности

• Каждый инструмент проверяет, что целевые пути остаются в пределах хранилища (src/obsidian_mcp/utils/path_safety.py), включая проверки с учётом символических ссылок.

• В TypeScript-оригинале была подтверждённая ошибка, из-за которой эта проверка фактически не срабатывала (асинхронная функция валидации вызывалась без await). В этом порте все функции безопасности путей синхронные, что структурно предотвращает такой класс ошибок.