Obsidian MCP Tools

黑曜石模型上下文协议工具

一种模型上下文协议（MCP）服务器，允许MCP客户端（Cursor、VSCode、Claude Desktop等）读取和搜索任何包含Markdown注释的目录，如黑曜石保险库。

此服务器公开了一个丰富的只读工具包 obsidian_-用于处理vault元数据（标签、链接、frontmatter）、文件名和全文内容的前缀MCP工具。

先决条件

• Node.js（v18或更高版本）
• npm（附带Node.js）
• 包含Markdown文件的黑曜石保险库或目录

安装

1.克隆存储库

git clone https://github.com/dp-veritas/mcp-obsidian-tools.git
cd mcp-obsidian-tools

2.安装依赖项

npm install

3.建设项目

npm run build

这将编译TypeScript代码并创建 dist/ 包含可执行文件的目录。

配置

构建后，您需要将此服务器添加到MCP客户端的配置中。配置格式因客户端而异，但通常遵循以下模式：

快速入门： 看 example-mcp-config.json 对于游标/VCode格式，或 example-claude-desktop-config.json 适用于克劳德桌面格式。

配置格式

在MCP客户端的配置文件中添加一个条目（通常 mcpServers 或 mcp.servers):

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-obsidian-tools/dist/index.js", "/path/to/your/vault"]
    }
  }
}

重要提示： 服务器位置和vault路径都使用绝对路径。

支持的路径格式

vault路径可以是：

• 绝对路径: /Users/username/Documents/MyVault
• 相对路径: ./my-vault （相对于当前工作目录）
• 主目录快捷方式: ~/Documents/MyVault

示例配置

对于光标

添加到光标MCP设置文件（位置因操作系统而异）：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/Users/username/path/to/mcp-obsidian-tools/dist/index.js", "/Users/username/Documents/MyVault"]
    }
  }
}

对于VSCode

添加到用户设置JSON(Ctrl+Shift+P → Preferences: Open User Settings (JSON))或创建 .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "obsidian": {
        "command": "node",
        "args": ["/Users/username/path/to/mcp-obsidian-tools/dist/index.js", "/Users/username/Documents/MyVault"]
      }
    }
  }
}

适用于克劳德桌面

添加到Claude Desktop的MCP配置文件（位置因操作系统而异）。Claude桌面配置可以包括 preferences 章节：

{
  "preferences": {
    "quickEntryShortcut": {
      "accelerator": "Alt+Space"
    }
  },
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/Users/username/path/to/mcp-obsidian-tools/dist/index.js", "/Users/username/Documents/MyVault"]
    }
  }
}

注： 看 example-claude-desktop-config.json 查看完整的Claude Desktop示例。看 example-mcp-config.json 用于光标/VCode格式。

全局安装（可选）

如果你更喜欢全局安装，这样你就可以在任何地方使用它：

npm install -g .

然后配置：

{
  "mcpServers": {
    "obsidian": {
      "command": "mcp-obsidian-tools",
      "args": ["/path/to/your/vault"]
    }
  }
}

可用工具

配置后，以下MCP工具将可用：

• obsidian_search_notes：按文件名搜索注释（不区分大小写，支持简单的正则表达式/通配符）。返回匹配的相对路径 .md 文件夹。

• obsidian_read_notes：按相对路径读取多个笔记的内容。每个音符都会返回其路径头；故障按注释报告。集 headersOnly: true 只返回标题（以开头的行 #)用于快速提取标题/结构。

• obsidian_list_tags：扫描所有Markdown文件并列出所有标签（frontmatter tags 和内联 #tags)具有发生计数。可选的 startsWith 过滤器。

• obsidian_notes_by_tag：给定一个或多个标记名，返回包含这些标记的所有注释路径（frontmatter或inline）。可选的 match 的 "any" 或 "all".

• obsidian_get_frontmatter：对于给定的笔记路径，将解析后的YAML frontmatter作为JSON返回（例如。 author, tags, created).

• obsidian_backlinks：给定目标笔记路径或名称，通过黑曜石维基链接列出链接到它的所有笔记([[Note Name]])或标记链接([Display](path)).

• obsidian_search_content：在笔记内容内进行全文搜索（不是文件名）。支持简单的通配符模式；可以只返回带有上下文的路径或片段。

• obsidian_query：对vault进行自然语言查询，可根据前台日期进行可选的日期过滤（例如。 created: YYYY-MM-DDTHH:MM:SS).

• obsidian_count_files：统计vault或特定子文件夹中的标记文件总数。支持模糊文件夹查找-如果像“History 101”这样的文件夹不在根目录，则会自动在整个vault中搜索匹配的文件夹。按直接子文件夹返回总数和明细。集 includeNames: true 还可以获取文件名列表（最多100个）。有助于了解vault大小、组织和文件夹中的文件列表。

所有工具都是 只读的 并通过路径验证严格限制在vault目录（及其真实/符号链接路径）中。

黑曜石_查询提示示例

• Which of my entries concern the overton window?
• Show interview candidate notes I've logged from the last 6 months
• Any daily notes about board-related topics this month?

故障排除

服务器未启动

• 检查路径：确保服务器路径和vault路径都是绝对路径
• 验证构建：一定要跑 npm run build 和那个 dist/ 目录存在
• 检查Node.js：确保已安装Node.js v18+(node --version)

工具未出现

• 重新启动客户端：添加配置后，重新启动MCP客户端（光标/VCode/Claude桌面）
• 检查日志：在MCP客户端的日志中查找错误消息
• 验证vault路径：确保保险库路径正确且可访问

权限错误

• 检查保管库权限：确保您具有vault目录的读取权限
• 检查服务器权限：确保 dist/index.js 文件是可执行的(chmod +x dist/index.js)

模型兼容性

工具调用质量取决于您的LLM。一些模型（尤其是较小的模型）可能难以为MCP工具格式化正确的参数，特别是在以下情况下：

• 复杂的自然语言查询
• 非英语输入
• 多个参数

如果遇到意外错误，请尝试：

1. 简化您的查询
2. 使用更大/更强大的模型（即Sonnet vs Haiku）
3. 检查您的MCP客户端是否处于正确模式（即游标中的代理或计划模式）

注： 复杂的交叉引用查询（例如，“X如何在我的保险库中与Y相关？”）可能需要10-30多次工具调用，因为模型会迭代不同的搜索策略。这是正常行为，不是失败。

发展

要观察开发过程中的变化：

npm run watch

许可证

看 许可证 文件以获取详细信息。