MCP obsidian notes

黑曜石笔记MCP服务器

一种MCP（模型上下文协议）服务器，提供对黑曜石笔记库的访问，而无需运行黑曜岩。此服务器允许您直接通过文件系统与黑曜石保管库交互，从而启用读取、写入、搜索和模板操作。

特性

• 文件操作：列出目录、读取文件、创建/更新笔记、删除项目
• 每日笔记：通过自动日期处理获取每日笔记（今天、昨天、明天、YYYY-MM-DD）
• 搜索：通过灵活的筛选在笔记内容、文件名和标签之间进行搜索
• 注意关系：根据共享标签或维基链接查找相关笔记
• 文本编辑：替换注释中的文本或附加到特定的标记部分
• 物业管理：更新黑曜石前体属性（添加、更新、删除）
• 模板系统：使用变量替换从模板创建注释
• 前线支援：在笔记中解析和操作YAML frontmatter

工具

核心文件操作

list_notes_directory

列出vault目录中的文件和目录。默认情况下返回文件和目录。当recursive=true时，只返回子目录中的.md文件。

参数：

• path （字符串，可选，默认值：“.”）：相对于vault根目录的目录路径（使用“.”表示根目录）
• limit （数字，可选，默认值：50）：要返回的最大项目数
• offset （数字，可选，默认值：0）：分页偏移
• recursive （boolean，可选，默认值：false）：如果为true，则递归搜索子目录并仅返回.md文件。如果为false，则立即返回内容（文件和目录）

退货： 如果路径不存在，则为空数组

read_notes_file

从vault中读取标记注释文件。分别返回内容正文（不含frontmatter）和frontmatter作为YAML元数据。

参数：

• path （字符串，必填）：相对于vault根目录的注释文件路径。可以包含或省略.md扩展名（如果缺少，则自动添加）

退货： 带有已解析前体的文件内容（分开）

delete_notes_item

从vault中删除文件或目录。递归删除目录。

参数：

• path （字符串，必填）：相对于vault根目录的文件或目录路径。对于文件，可以包含或省略.md扩展名。对于目录，不得包含.md扩展名

退货： 路径不存在时出错

create_or_update_note

创建新笔记或更新现有笔记。路径不应包含.md扩展名（自动添加）。模式选项：“覆盖”（默认）-替换整个文件，“附加”-在现有正文后添加内容，“预置”-在已有正文前添加内容。Frontmatter已合并（添加新密钥，更新现有密钥）。如果需要，创建父目录。

参数：

• path （字符串，必填）：注释相对于vault根的路径。不应包含.md扩展名（自动添加）
• content （string，必填）：注释内容体（不含前体）
• frontmatter （object，可选）：YAML frontmatter元数据。如果存在注释，则合并frontmatter（添加新密钥，更新现有密钥）
• mode （字符串，可选，默认值：“overwrite”）：更新模式-“override”（替换整个文件），“append”（在现有正文后添加内容），“prepend”（在已有正文前添加内容）

get_daily_note

获取约会的每日笔记。搜索常用位置：配置的daily_notes_path、根、“daily/”、“daily notes/”。

参数：

• date （字符串，可选，默认值：“today”）：日期格式：“tody”、“yesterday”、“tomorrow”或“YYYY-MM-DD”

退货： 如果未找到注释，则内容字段中会显示错误消息

高级搜索和发现

search_vault

在vault注释中搜索文本。查询是文字文本（区分大小写的子字符串匹配）。可以指定多个作用域。返回文件路径和匹配预览。

参数：

• query （字符串，必填）：搜索查询-文字文本（区分大小写的子字符串匹配）
• scope （数组，可选，默认值：\[“内容”，“文件名”\]）：搜索范围：“内容”数组（注释体），“文件名称”数组（文件路径），“标签”数组（frontmatter标签）。可以指定多个
• path_filter （字符串，可选）：将搜索限制到相对于vault根目录的特定子目录

find_related_notes

查找与源注释相关的注释。从源代码注释的frontmatter中提取标签，并从内容中提取维基链接\[\[…\]\]。查找其他注释：（1）在frontmatter中具有匹配的标签，或（2）具有与提取的链接名称匹配的文件名。

参数：

• path （字符串，必填）：相对于vault根的源注释路径。可以包含或省略.md扩展名（自动添加）
• on （数组，可选，默认值：\[“tags”，“links”\]）：关系条件：“tags（标签）”和/或“links（链接）”数组。从内容的frontmatter和wikilinks中提取标签，然后找到具有匹配标签或文件名的注释

退货： 如果未找到源注释，则为空数组

replace_text_in_note

替换注释中的文本。查找目标文本并将其替换为新内容。简单的查找和替换操作。

参数：

• path （字符串，必填）：相对于vault根目录的注释文件路径。可以包含或省略.md扩展名（自动添加）
• find （string，必填）：要在注释中查找的文本
• replace （字符串，必填）：替换文本。 \n in字符串转换为换行符
• replace_all （布尔值，可选，默认值：true）：如果为true，则替换所有出现的值。如果为false，则仅替换第一个匹配项

append_to_section

将文本附加到特定的标记部分。查找节标题，并将内容附加到相同或更高级别的下一个标题之前（或文件末尾）。

参数：

• path （字符串，必填）：相对于vault根目录的注释文件路径。可以包含或省略.md扩展名（自动添加）
• section_header （字符串，必填）：带#标记的节标题（例如，“##结束日”）。必须包含#以指定级别。空白区域已正常化。必须完全匹配（级别和文本）
• text_to_append （string，必填）：要附加到节中的文本。 \n in字符串转换为换行符。换行符会自动添加到此文本之前

错误：

• 如果未指定标头级别（无#标记），则返回错误
• 如果未找到部分，则返回错误
• 如果标头级别不匹配，则返回错误（例如，查找 # End day 但只有 ## End day 存在）
• 如果多个部分匹配，则返回错误（建议使用 replace_text_in_note 用于精确定位）

update_note_properties

在注释中更新前体属性（黑曜石属性）。更新/添加属性并删除指定的属性。不修改注释内容正文。如果前体不存在，则创建前体。

参数：

• path （字符串，必填）：相对于vault根目录的注释文件路径。可以包含或省略.md扩展名（自动添加）
• properties （对象，可选）：要更新或添加的属性。具有相同密钥的现有属性将被覆盖。添加了新属性。值可以是字符串、数字、布尔值或数组
• remove （字符串数组，可选）：要从frontmatter中删除的属性键

示例：

• 更新状态： {"properties": {"status": "done"}}
• 添加多个属性： {"properties": {"priority": "high", "due-date": "2024-01-15", "completed": true}}
• 删除属性： {"remove": ["old-tag", "deprecated-field"]}
• 更新和删除： {"properties": {"status": "archived"}, "remove": ["active"]}

模板系统

create_note_from_template

使用变量替换从模板创建注释。模板路径：如果以“/”开头或包含“：”，则视为相对于vault根的绝对路径；否则相对于templates目录（可以直接使用listnotes_templates中的路径）。

参数：

• path （字符串，必填）：新注释相对于vault根的目标路径。应包含.md扩展名
• template_path （string，必填）：模板文件的路径。如果以“/”开头或包含“：”，则视为绝对路径；否则与模板目录相关
• variables （object，可选）：用于模板替换的键值对。替换模板中的｛｛variable｝｝占位符

list_notes_templates

列出templates目录中的所有.md模板文件。返回相对于模板目录的路径（可以直接与create_note_from_template一起使用）。

参数： 无

退货： 模板文件路径、名称和大小。如果模板目录不存在，则返回空数组

建筑

cargo build --release

跑步

服务器通过stdio（标准输入/输出）进行通信，并需要 VAULT_LOCATION 要设置的环境变量：

export VAULT_LOCATION="/path/to/your/obsidian/vault"
./target/release/mcp_obsidian_notes

或使用货物：

export VAULT_LOCATION="/path/to/your/obsidian/vault"
cargo run --release

环境变量

必修的：

• VAULT_LOCATION：黑曜石保管库目录的根路径

可选：

• DAILY_NOTES_PATH：每日笔记文件夹的路径（相对于vault根目录，默认：“每日”或“每日笔记”）
• WEEKLY_NOTES_PATH：每周笔记文件夹的路径（相对于vault根目录）
• MONTHLY_NOTES_PATH：每月笔记文件夹的路径（相对于vault根目录）
• TEMPLATES_PATH：模板文件夹的路径（相对于vault根目录，默认：“templates”或“templates”）

例子：

export VAULT_LOCATION="/home/user/Documents/MyVault"
export DAILY_NOTES_PATH="Daily Notes"
export TEMPLATES_PATH="Templates"
./target/release/mcp_obsidian_notes

MCP客户端配置

要将此服务器与MCP客户端一起使用，请将其配置为使用stdio传输运行此二进制文件。

示例配置（适用于Claude Desktop或类似设备）：

{
  "mcpServers": {
    "obsidian-notes": {
      "command": "/path/to/mcp_obsidian_notes/target/release/mcp_obsidian_notes",
      "args": [],
      "env": {
        "VAULT_LOCATION": "/path/to/your/obsidian/vault",
        "DAILY_NOTES_PATH": "Daily Notes",
        "TEMPLATES_PATH": "Templates"
      }
    }
  }
}

拱顶结构

服务器使用标准黑曜石保险库结构：

vault/
├── Daily Notes/
│   ├── 2024-01-15.md
│   └── 2024-01-16.md
├── Templates/
│   ├── Meeting Template.md
│   └── Note Template.md
├── Project A/
│   └── notes.md
└── other-notes.md

前线支援

完全支持带有YAML frontmatter的注释：

---
title: My Note
tags: [work, important]
created: 2024-01-15
---

Note content here...

服务器可以读取、解析和更新frontmatter，同时保留笔记内容。

安全

所有文件操作都经过验证，以确保它们保留在vault根目录中，从而防止目录遍历攻击。在任何文件操作之前，路径都会被规范化并检查。

许可证

麻省理工学院