Obsidian Vault MCP Server

关键词

Obsidian笔记索引全文检索笔记链接任务统计

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个 MCP 服务器，用于为本地 Obsidian Vault 提供只读的上下文服务，方便将笔记内容、元数据、链接关系和任务信息等通过 MCP 以标准化的 JSON-RPC 形式暴露给 LLM 客户端（如 Claude Desktop）。
    • 服务器核心职责包括：托管与管理资源（Notes），注册与执行工具（Tools），定义并渲染 Prompts，并通过 JSON-RPC 与客户端通信。客户端可读取笔记、进行全文检索、获取 backlinks、解析 wikilinks、执行任务统计等功能。

  • 主要功能点

    • 资源与读取
      • obsidian_read_note：按路径或标题读取笔记全文及元信息。
      • obsidian_list_notes：按 PARA 区域、文件夹、标签和时间筛选笔记元数据。
      • obsidian_get_backlinks：查找指向指定笔记的所有笔记。
      • obsidian_resolve_link：将 wikilink 解析为目标笔记。
      • obsidian_get_unarchived_daily_notes：获取未归档的日记笔记信息。
    • 搜索与筛选
      • obsidian_search_notes：对笔记内容进行全文检索，支持 PARA、文件夹、 limit 等筛选。
      • obsidian_gather_topic：基于主题聚合相关笔记及片段，支持 backlinks 信息。
    • 任务与活动
      • obsidian_get_task_stats：统计一个文件夹内的任务信息（总数、完成、活跃、阻塞、 overdue 等）。
      • obsidian_get_project_activity：返回每个项目笔记的活动与任务统计摘要。
      • obsidian_get_weekly_summary：给出最近一段时间的周览（活动、完成等）。
    • 笔记创建与附件
      • obsidian_create_daily_note：创建日记笔记（每日笔记）。
      • obsidian_create_inbox_note：在 INBOX 目录创建笔记（便签/捕捉待处理内容）。
      • obsidian_create_note：在指定 PARA 区域创建笔记（可选子文件夹）。
      • obsidian_add_attachment：向档案区添加附件，支持路径或 Base64 内容，并可在笔记中添加 wikilink。
      • obsidian_get_unarchived_daily_notes、obsidian_extract_note_tasks、obsidian_update_daily_note：日记与任务相关的扩展功能。
    • 架构与安全
      • 只读、局部本地运行、对 Vault 的访问经过严格的文件操作处理，保证数据安全性与一致性。

  • 安装步骤

    • 克隆代码并安装依赖
    • 设定 Obsidian Vault 路径（环境变量 OBSIDIAN_VAULT_PATH，或按默认配置覆盖）
    • 运行 MCP 服务器（示例命令为在本地运行模块入口）
    • 将服务器注册到 Claude Desktop 或其他 MCP 客户端的配置中
    • 如需日志与调试，可配置日志级别与日志路径

  • 服务器配置（MCP 客户端需要的最小信息，可用于启动并连接到 MCP 服务器） { "server_name": "obsidian-vault", "command": "/path/to/venv/bin/python", "args": [ "-m", "obsidian_vault_mcp" ], "env": { "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault", "OBSIDIAN_VAULT_LOG_LEVEL": "INFO" }, "_comment": "server_name 对应 MCP 服务器名称；command 与 args 指定启动服务器的运行命令（使用虚拟环境中的 Python 解释器并以模块方式启动），env 中必须提供实际的 Obsidian Vault 路径与日志级别。" }

  • 基本使用方法

    • 启动服务器后，打开 Claude Desktop 或其他 MCP 客户端，在对话中调用上述工具（如读取笔记、搜索、任务统计等）并获得格式化的文本结果或原始 JSON 数据。
    • 使用示例场景：读取指定笔记、搜索包含关键词的笔记、获取某个文件夹的任务统计、在 INBOX 创建笔记等。
    • 如遇到访问权限或路径配置问题，请确保 OBSIDIAN_VAULT_PATH 指向本地 Vault 的正确路径，Vault 目录及笔记文件具有可读权限，且本服务在本地运行无网络访问需求。

  • 额外信息

    • 安装与运行的入口点在 package 配置中声明为 obsidian-vault-mcp，直接通过 python -m obsidian_vault_mcp 启动即可。
    • 服务器实现包含资源、工具的完整注册、参数验证及格式化返回，便于集成到任意支持 MCP 的客户端。

服务器信息

访问项目