Obsidian MCP Server

obsidian-mcp-server — это MCP-сервер, который позволяет ИИ-агентам просматривать, искать и обобщать документы Markdown в Obsidian Vault.

Подключите его к MCP-клиенту, чтобы дать агенту возможность просматривать содержимое Vault, контролируя при этом использование токенов.

Что можно делать

• Поиск заметок по ключевым словам (vault, action="search")

• Чтение конкретной заметки (vault, action="read")

• Просмотр списка всех документов в Vault (vault, action="list_all")

• Просмотр состояния Vault (vault, action="stats")

• Создание пакетов памяти для долгосрочного контекста (vault, action="collect_context")

• Просмотр сохраненных заметок памяти (vault, action="load_memory")

• Предложение автоматической генерации frontmatter (generate_property)

• Применение frontmatter (write_property)

• Рабочий процесс создания документов на основе промптов (create_document_with_properties)

• Организация вложений изображений (organize_attachments)

Меры предосторожности

Этот сервер открывает содержимое Vault для клиента. Используйте его с осторожностью в производственных средах.

• Не подключайтесь к ненадежным ИИ-агентам.

• Ограничьте путь к Vault (VAULT_DIR_PATH) минимально необходимыми правами доступа.

• Для больших Vault контролируйте расходы на токены, регулируя maxOutputChars и limit.

• Режим сжатия по умолчанию для действия vault — balanced.

Проверка настроек

1. Путь к Vault: В VAULT_DIR_PATH необходимо указывать абсолютный путь.

// ✅ 올바른 예시
"VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
"VAULT_DIR_PATH": "C:\\Users\\username\\Documents\\MyVault"  // Windows
"VAULT_DIR_PATH": "/mnt/c/Users/username/Documents/MyVault"  // WSL

// ❌ 잘못된 예시
"VAULT_DIR_PATH": "~/Documents/MyVault"  // 상대 경로 사용 불가
"VAULT_DIR_PATH": "./vault"              // 상대 경로 사용 불가

2. Требования к Node.js: Должна быть установлена Node.js версии 22 или выше.

node --version  # v22.0.0 이상 확인

Начало работы (быстрая настройка)

1) Общие требования

• Минимальная настройка — VAULT_DIR_PATH (абсолютный путь к Vault).

• Запуск MCP описан на основе дистрибутивного пакета.

  • Использование дистрибутивного пакета (npx) (рекомендуется)

  • Локальный build/index.js предназначен для разработки/отладки

• Локальный запуск описан отдельно в последнем разделе (5).

• Если путь к Vault не указан, запуск завершится ошибкой.

• Примеры ниже приведены в удобном для копирования виде.

2) Настройка дистрибутивного пакета (npx)

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": {
        "VAULT_DIR_PATH": "/abs/path/to/your/vault",
        "LOGGING_LEVEL": "info"
      }
    }
  }
}

Прямой запуск CLI:

npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault --logging-level info

3) Конфигурация MCP Client

Даже если интерфейс у клиентов отличается, базовая форма command/args/env одинакова.

Основное для дистрибутивного пакета: command="npx", args=["-y","@sunub/obsidian-mcp-server@latest"], env.VAULT_DIR_PATH

[mcp_servers.obsidian]
command = "npx"
args = ["-y", "@sunub/obsidian-mcp-server@latest"]
env = { VAULT_DIR_PATH = "/abs/path/to/your/vault" }

1. Запустите copilot

2. /mcp add

3. Введите следующие значения

• Server name: obsidian

• Server Type: [1] Local

• Command: npx -y @sunub/obsidian-mcp-server@latest

• Environment: { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }

Поскольку названия ключей JSON могут отличаться в зависимости от версии (например, servers/mcpServers), применяйте их в соответствии с документацией вашего проекта.

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
    }
  }
}

Зарегистрируйте в Cursor Settings → MCP → New MCP Server.

{
  "obsidian": {
    "command": "npx",
    "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
    "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
  }
}

※ В некоторых версиях имя ключа идентификатора сервера может отличаться, следуйте инструкциям на экране настроек.

Пример установки пакета:

gemini mcp add obsidian npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault

※ В некоторых версиях Gemini поддержка --vault-path может отличаться, поэтому проверьте актуальную документацию gemini mcp add.

4) Пример готовой конфигурации

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y",
        "@sunub/obsidian-mcp-server@latest"
      ],
      "env": {
        "VAULT_DIR_PATH": "/path/to/obsidian-vault",
        "VAULT_METRICS_LOG_PATH": "/path/to/vault-metrics.ndjson",
        "LOGGING_LEVEL": "info"
      }
    }
  }
}

Настройка переменных окружения

• VAULT_DIR_PATH (обязательно): Абсолютный путь к Obsidian Vault

• VAULT_METRICS_LOG_PATH (опционально): Запись метрик сжатия/токенов ответов в формате JSONL

• LOGGING_LEVEL (опционально): debug | info | warn | error

Быстрая проверка после запуска

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

1. Проверка состояния Vault

"Vault 상태를 요약해줘."

Ожидаемое внутреннее действие:

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": { "action": "stats" }
  }
}

При нормальной работе ответ будет содержать totalFiles, isInitialized, vaultPath.

2. Проверка индекса поиска

"노트 제목에 'MCP'가 들어간 문서만 5개 찾아줘."

Ожидаемое внутреннее действие:

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": {
      "action": "search",
      "keyword": "MCP",
      "limit": 5
    }
  }
}

Если результат search пуст, проверьте индексацию/путь или область поиска по ключевым словам.

3. Проверка чтения документа

"특정 노트 하나를 읽어줘."

Ожидаемое внутреннее действие:

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": {
      "action": "read",
      "filename": "예: 어떤 문서 이름"
    }
  }
}

Если filename указан неверно, придет { "error": "Document not found: ..." }. Если это произошло, сначала проверьте кандидатов с помощью list_all вместо read.

Для search, list_all, load_memory значение по умолчанию quiet равно true, поэтому базовый ответ может быть кратким. При необходимости используйте quiet: false, includeContent: true, excerptLength (или maxOutputChars) для получения подробной информации.

Примеры использования

Важнее не то, как вызывается MCP, а «какое действие вы хотите выполнить».

Пример действия по организации вложений, описанных в документе Markdown:

https://github.com/user-attachments/assets/eb74ec05-09f7-4632-a22c-666b7e844147

• Если вы попросите организовать вложения изображений, указанные в документе, он создаст папку с именем файла внутри папки images и переместит их туда.

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

Примеры вопросов для прямого выполнения:

• Найди только раздел "MCP Client configuration" в "시작하기 (빠른 설정)" в README.md.

• Прочитай и обобщи только пример настройки "vault" в "docs/tools-usage-guide.md".

• Найди только параметры "collect_context" для "vault" в "docs/tool-reference.md".

• Обобщи только блок настройки "MCP 서버" в "docs/tools-usage-guide.md".

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

• "Найди только примеры команд запуска в разделе начала работы в README.md"

• "Найди и сравни примеры использования, связанные с vault, в docs/tools-usage-guide.md"

• "Прочитай только описание параметров vault.read в docs/tool-reference.md"

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

• Покажи только пример npx в "시작하기 (빠른 설정)" в README.md → Сначала извлекаются ключевые слова и вызывается vault.search.

• Прочитай только параметр collect_context в docs/tool-reference.md → Сначала читается соответствующая часть документа через vault.read, при необходимости обобщается через vault.collect_context.

• Прочитай процесс обработки frontmatter в docs/tools-usage-guide.md → После нахождения расположения документа через vault.read могут быть последовательно вызваны generate_property/write_property/create_document_with_properties.

Потоки вызовов инструментов можно увидеть вместе с конкретными примерами JSON в Примеры использования (потоки вызовов инструментов).

Зарегистрированные инструменты

• Obsidian Tools (6 actions)

  • vault

    • search

    • read

    • list_all

    • stats

    • collect_context

    • load_memory

• generate_property

• write_property

• create_document_with_properties

• organize_attachments

Подробные правила использования

• Подробное описание работы инструментов, значения параметров по умолчанию и фактические форматы ответов см. в Tool Reference.

• vault — это один инструмент MCP, а фактическое действие определяется значением action. Опечатки — самая частая причина сбоев.

• В больших Vault начинайте с collect_context с scope="all" и небольшим значением maxDocs, постепенно расширяя область.