使用说明

黑曜石MCP服务器

通过模型上下文协议（MCP）提供对黑曜石金库的实时Claude AI访问

概述

此MCP服务器使Claude能够查询、搜索和读取黑曜石金库中的笔记 没有令牌限制与将所有文档加载到上下文中的Claude Projects不同，此服务器提供对您的知识库的动态、按需访问。

特性

多保险库支持：从单个MCP服务器实例为多个黑曜石保管库提供服务（v2.0）
实时保险库访问：动态查询和阅读笔记，无需预先上传
自动索引更新：文件系统监视器在注释更改时自动更新矢量索引（v1.3.0）
向量搜索：使用本地嵌入（Transformers.js）或Anthropic API进行语义搜索
混合搜索：结合关键字和语义搜索以获得最佳结果
写入操作：以编程方式创建、更新和删除笔记
跨保险库搜索：使用以下命令搜索所有已配置的保管库 vault: "*"
搜索工具：基于关键字、标记和文件夹的筛选
多种格式：JSON和Markdown响应格式
安全：路径验证和安全检查可防止未经授权的访问
代币高效：没有保险库大小限制或令牌约束

快速开始

先决条件

Node.js 18+（推荐20+）
TypeScript 5.7+
黑曜石拱顶 带有标记注释
克劳德桌面版 或MCP兼容客户端

安装

Windows（PowerShell）：

# 1. Clone or navigate to repository
cd /path/to/obsidian-mcp-server

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build

# 4. Verify build succeeded
Test-Path dist\index.js  # Should return True

macOS/Linux（Bash）：

# 1. Clone or navigate to repository
cd ~/obsidian-mcp-server

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build

# 4. Verify build succeeded
ls dist/index.js  # Should exist

配置

创建 config.json 在vault的项目根目录中：

{
  "vaults": [
    {
      "name": "work",
      "path": "C:\\Users\\YourName\\Documents\\WorkVault",
      "enableWrite": true
    },
    {
      "name": "personal",
      "path": "C:\\Users\\YourName\\Documents\\PersonalVault",
      "enableWrite": false
    }
  ],
  "vectorSearch": {
    "enabled": true,
    "provider": "transformers",
    "model": "Xenova/bge-small-en-v1.5",
    "indexOnStartup": "auto"
  },
  "searchOptions": {
    "maxResults": 20,
    "excerptLength": 200,
    "caseSensitive": false,
    "includeMetadata": true
  },
  "logging": {
    "level": "info",
    "file": "logs/mcp-server.log"
  }
}

选择正确的嵌入模型：

默认模型(Xenova/bge-small-en-v1.5)在384个维度上提供卓越的品质。根据您的需求考虑替代方案：

默认: Xenova/bge-small-en-v1.5 --最佳质量资源比，建议用于多保险库设置
高端CPU （Ryzen 9+、i9+、M3 Max+）：使用 Xenova/bge-base-en-v1.5 为了获得最佳质量（768昏暗，约2倍RAM）
多语言保险库：使用 Xenova/paraphrase-multilingual-MiniLM-L12-v2

看语义搜索指南以进行详细的模型比较。

初始索引（大型保险库需要）

重要提示： 对于包含1000多个注释的保管库或切换嵌入模型时，请运行初始索引独立在使用Claude Desktop之前。

快速入门：

# Windows
$env:OBSIDIAN_VAULT_PATH = "X:\Path\To\Your\Vault"
$env:OBSIDIAN_CONFIG_PATH = "D:\repos\obsidian-mcp-server\config.json"
node --expose-gc --max-old-space-size=16384 dist\index.js

# macOS/Linux
export OBSIDIAN_VAULT_PATH="/path/to/vault"
export OBSIDIAN_CONFIG_PATH="$HOME/obsidian-mcp-server/config.json"
node --expose-gc --max-old-space-size=16384 dist/index.js

索引完成后，配置Claude Desktop（见下文）以供日常使用。

📚 看索引工作流程指南 有关详细说明、故障排除和型号切换程序。

Claude桌面集成

视窗

编辑Claude桌面配置：

# Config location: %APPDATA%\Claude\claude_desktop_config.json
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

添加此配置：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "--expose-gc",
        "--max-old-space-size=16384",
        "/path/to/obsidian-mcp-server/dist/index.js"
      ],
      "env": {
        "OBSIDIAN_CONFIG_PATH": "/path/to/obsidian-mcp-server/config.json"
      }
    }
  }
}

macOS

编辑Claude桌面配置：

# Config location: ~/Library/Application Support/Claude/claude_desktop_config.json
vi ~/Library/Application\ Support/Claude/claude_desktop_config.json

添加此配置：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "--expose-gc",
        "--max-old-space-size=16384",
        "/path/to/obsidian-mcp/dist/index.js"
      ],
      "env": {
        "OBSIDIAN_CONFIG_PATH": "/path/to/obsidian-mcp-server/config.json"
      }
    }
  }
}

多保险库设置

服务器通过以下方式原生支持多个保管库 vaults 数组in config.json。所有保管库都由单个MCP服务器进程提供服务，每个保管库不需要单独的服务器条目。

每个保险库都有自己的独立矢量索引（存储在每个保险库的 .mcp-vector-store/ 文件夹）和文件监视器。使用 vault 所有工具上的参数，以针对特定的保险库，或 "*" 使用读取工具在所有保险库中搜索。

{
  "vaults": [
    {
      "name": "work",
      "path": "C:\\Users\\YourName\\Documents\\WorkVault",
      "enableWrite": true
    },
    {
      "name": "personal",
      "path": "C:\\Users\\YourName\\Documents\\PersonalVault",
      "enableWrite": false
    }
  ],
  "vectorSearch": {
    "enabled": true,
    "provider": "transformers",
    "model": "Xenova/bge-small-en-v1.5",
    "indexOnStartup": "auto"
  }
}

内存规划：每个保险库独立加载嵌入模型（每个保险库约150-300MB RAM，具体取决于模型）。相应地计划内存。

传统注释： 如果您以前使用过 OBSIDIAN_VAULT_PATH 每个保管库有一个服务器进程，服务器会自动将其迁移到单个保管库 vaults 阵列在启动时。旧的多过程方法仍然有效，但不再被推荐。

重新启动克劳德桌面

在配置之后， 完全退出并重新启动Claude Desktop 以使更改生效。

文档

索引工作流程指南 -初始设置、型号切换和故障排除
配置指南 -完整的配置参考
语义搜索指南 -语义搜索设置和使用

用法

克劳德对话

配置后，Claude可以自动访问您的保管库：

User: "Search my vault for notes about Python debugging"

Claude will use: obsidian_search_vault(query="Python debugging")
Returns: Matching notes with excerpts and URIs

User: "Show me the full Getting-Started note"

Claude will read: obsidian://vault/Guides/Getting-Started.md
Returns: Complete note content

可用工具

所有工具都需要 vault 指定要操作哪个vault的参数。使用您的vault名称 config.json.阅读工具也接受 "*" 用于跨保险库搜索。

黑曜石_列表_结果

列出所有已配置的保管库及其状态和元数据。

参数：无需。

退货：Vault名称、路径、写入状态和索引运行状况（注释数、型号、索引日期）。

黑曜石搜索结果

按关键字、标签或文件夹搜索vault。

参数：

vault （必填）：保险库名称或 "*" 适用于所有保险库
query （必填）：搜索关键字（空格分隔）
tags （可选）：按标签筛选（必须全部）
folders （可选）：仅限于特定文件夹
limit （可选）：最大结果（1-100，默认值：20）
offset （可选）：分页偏移量（默认值：0）
response_format （可选）：“markdown”或“json”（默认：“markdown”）

示例：

// Search a specific vault
obsidian_search_vault((vault = "work"), (query = "JavaScript testing"));

// Search across all vaults
obsidian_search_vault((vault = "*"), (query = "project"), (tags = ["active"]));

黑曜石浪漫搜索

使用语义相似性（基于意义）而不是关键字匹配来搜索vault。

参数：

vault （必填）：保险库名称或 "*" 适用于所有保险库
query （必填）：自然语言查询（1-500个字符）
limit （可选）：最大结果（1-50，默认值：10）
min_score （可选）：相似性阈值（0-1，默认值：0.5）
hybrid （可选）：结合关键字搜索（默认：false）
response_format （可选）：“markdown”或“json”（默认：“markdown”）

示例：

// Semantic search in one vault
obsidian_semantic_search((vault = "work"), (query = "machine learning ethics"));

// Cross-vault hybrid search
obsidian_semantic_search(
  (vault = "*"),
  (query = "web development best practices"),
  (hybrid = true)
);

黑曜石read_note

使用解析的frontmatter阅读特定笔记的完整内容。只读操作。

参数：

vault （必填）：保险库名称（否 "*")
path （必填）：注释的相对路径（例如，“Projects/MyNote.md”）
response_format （可选）：“markdown”或“json”（默认：“markdown”）

黑曜石创造笔记

在特定vault中创建新注释。必须为目标保管库启用写入功能。

参数：

vault （必填）：保险库名称（否 "*")
path （必填）：新注释的相对路径（例如，“Projects/NewNote.md”）
content （必填）：注释内容（标记）
frontmatter （可选）：YAML frontmatter对象

黑曜石_更新_注释

更新现有笔记的内容或封面。

参数：

vault （必填）：保险库名称（否 "*")
path （必填）：注释的相对路径
content （可选）：新内容（替换现有内容）
frontmatter （可选）：新的前台（与现有前台合并）
append （可选）：追加内容而不是替换（默认值：false）

黑曜石_delete_note

从特定vault中删除注释。必须为目标保管库启用写入功能。

参数：

vault （必填）：保险库名称（否 "*")
path （必填）：注释的相对路径
confirm （必填）：必须 true 确认删除

可用资源

保管库中的每个笔记都作为URI的资源公开：

obsidian://vault/{vaultName}/[relative-path]

Claude可以列出所有可用的笔记，并通过URI读取特定的笔记。

建筑

设计理念

此服务器使用 仅限搜索工具 方法而不是预先注册数千个个人资源：

高效：克劳德使用 obsidian_search_vault 动态查找笔记
可扩展的：适用于任何大小的金库（用5000多张纸币测试）
快：资源注册后无启动延迟
符合MCP标准：遵循大型数据集的最佳实践

克劳德通过搜索发现笔记，收到 obsidian://vault/ URI，然后可以根据需要读取特定的注释。

组件图

graph LR
    A[Claude AI] -->|MCP Protocol| B[MCP Server]
    B -->|stdio| A
    B --> C[Vault Registry]
    C --> D1[Vault: work]
    C --> D2[Vault: personal]
    D1 --> E1[Search Engine]
    D1 --> F1[Vector Store]
    D1 --> G1[File Watcher]
    D2 --> E2[Search Engine]
    D2 --> F2[Vector Store]
    D2 --> G2[File Watcher]

组件

index.ts -服务器初始化、多保险库设置和传输
黑曜石服务器.ts -带vault路由的MCP请求处理程序（资源、工具）
保险库调节 -多保险库上下文管理和解析
search.ts -具有评分和过滤功能的搜索引擎
嵌入s.ts -矢量存储和嵌入生成
utils.ts -配置、文件操作、安全

安全

路径验证

所有文件路径都经过验证，以防止目录遍历攻击：

// Checks that requested path is within vault boundaries
if (!isPathSafe(notePath, vaultPath)) {
  throw new Error("Access denied: path outside vault");
}

只读模式

默认情况下，服务器为只读。要启用写入操作（未来功能）：

{
  "enableWrite": true
}

输入消毒

Zod模式 验证所有工具输入
路径规范化 防止Windows/Unix路径问题
查询限制 防止资源耗尽（最多500个字符）

发展

构建

npm run build

开发模式（热重载）

npm run dev

掉毛

npm run lint
npm run format

测试

npm test

故障排除

服务器未启动

检查保险库路径：

# Windows
Test-Path "C:\Users\YourName\Documents\ObsidianVault"  # Should return True

# macOS/Linux
ls -la ~/Documents/ObsidianVault  # Should show folder contents

检查构建输出：

# Windows
Test-Path .\dist\index.js  # Should return True

# macOS/Linux
ls dist/index.js  # Should exist

查看错误日志：

# All platforms
node dist/index.js

Claude找不到服务器

验证配置文件位置：
- 窗户： %APPDATA%\Claude\claude_desktop_config.json
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
检查JSON语法： 使用JSON验证器
完全重新启动克劳德桌面 （不要只是关窗户）
检查克劳德日志：
- 窗户： %APPDATA%\Claude\logs\
- macOS： ~/Library/Logs/Claude/

搜索未返回任何结果

检查排除模式 -您的笔记可能被排除在外
验证文件扩展名 -只有 .md 文件已编入索引
检查查询条件 -尝试更宽泛的术语

权限错误

确保您的用户具有读取权限：

Vault目录
所有子目录
全部 .md 文件

配置选项

完整配置架构：

{
  vaults: Array<{                   // Vault definitions (required)
    name: string;                   // Unique vault identifier
    path: string;                   // Absolute path to vault
    enableWrite?: boolean;          // Per-vault write override
    includePatterns?: string[];     // Per-vault include override
    excludePatterns?: string[];     // Per-vault exclude override
    vectorSearch?: { ... };         // Per-vault vector config override
  }>;
  includePatterns: string[];        // Default glob patterns to include
  excludePatterns: string[];        // Default glob patterns to exclude
  enableWrite: boolean;             // Default write permission (default: false)
  vectorSearch?: {                  // Default vector search config
    enabled: boolean;               // Enable semantic search
    provider: "transformers";       // Embedding provider
    model?: string;                 // Model name (default: Xenova/bge-small-en-v1.5)
    indexOnStartup: "auto" | "always" | "never" | boolean;
  };
  searchOptions: {
    maxResults: number;             // Max search results (default: 20)
    excerptLength: number;          // Excerpt length (default: 200)
    caseSensitive: boolean;         // Case-sensitive search (default: false)
    includeMetadata: boolean;       // Include frontmatter (default: true)
  };
  logging: {
    level: string;                  // Log level (default: "info")
    file: string;                   // Log file path
  };
}

演出

优化策略

懒加载 -仅在请求时读取文件
分页 -限制搜索结果
字符限制 -截断大响应
排除模式 -跳过不必要的文件

建议限值

保险库大小：<10000张钞票
搜索结果：每个查询<100
文件大小：每张钞票<10MB

未来的增强功能

索引 -预构建搜索索引以实现更快的查询
缓存 -缓存前台和元数据
向量搜索 -语义相似度搜索
观看模式 -实时文件系统监控

MCP协议合规性

此服务器遵循 MCP最佳实践:

✅ Zod输入验证
✅ 工具注释（readOnlyHint、destructiveHint等）
✅ 多种响应格式（JSON/Markdown）
✅ 截断字符限制（25k）
✅ 正确的错误处理
✅ 分页支持
✅ 安全验证
✅ 描述性工具文档
✅ 大型数据集的搜索工具模式

更新日志

v2.0.0（2025年1月）-多保险库支持

新功能:

✅ 多保险库支持：从单个MCP服务器实例为多个黑曜石保管库提供服务
✅ obsidian_list_vaults 工具：列出所有已配置的Vault及其索引运行状况和元数据
✅ vault 参数：所有工具都需要 vault 显式瞄准参数
✅ 跨保险库搜索：使用 vault: "*" 使用read工具搜索所有保险库
✅ 根据保险库配置：覆盖每个vault的写入权限、包含/排除模式和矢量搜索设置
✅ 每个vault文件监视器：每个保管库独立的文件监视和自动索引
✅ 更新的URI方案: obsidian://vault/{vaultName}/{path} 包括vault上下文

配置:

✅ vaults 数组：在中定义多个Vault config.json
✅ 遗留迁移: OBSIDIAN_VAULT_PATH env-var自动迁移到单个保管库 vaults 数组
✅ 每个保险库覆盖：enableWrite、includePattern、excludePatterns、vectorSearch从服务器默认值继承

重大变更:

⚠️ vault 参数必填：现在所有工具都需要 vault 参数
⚠️ URI方案已更改：URI现在包括保管库名称： obsidian://vault/{vaultName}/{path}
⚠️ 配置格式: vaults array是推荐的配置格式（传统的自动迁移保留了向后兼容性）

迁移:

现有配置 OBSIDIAN_VAULT_PATH 通过自动迁移继续工作
更新工具调用以包括 vault 参数
更新任何URI解析以处理新的 {vaultName} 段

v1.4.0（2025年12月）-并行批处理和智能自动索引

性能改进:

🚀 索引速度提高10倍：使用Promise.all进行并行批处理（10个并发嵌入）
⚡ 65倍加速：5681个笔记在5.5分钟内被索引（低于6小时以上）
💾 强大的检查点：适当的Vectra事务管理（beginUpdate/endUpdate）
🔧 内存优化：检查点显式GC，管道每500个音符刷新一次
📊 生产测试：已成功索引5681/6056个笔记（覆盖率93.8%）

新功能:

✅ 聪明的 indexOnStartup 模式: "auto" （智能检测）， "always", "never"
✅ 自动模型更改检测：切换型号时无需手动切换配置
✅ 指标验证：检测缺失、损坏或不兼容的索引
✅ 模型元数据存储：将模型信息存储在索引中以供验证
✅ 无缝模型切换：只需在配置中更改模型并重新启动-自动重新索引

错误修复:

✅ 固定检查点持久性：Vectra索引现在已在检查点正确刷新到磁盘
✅ 消除了指数损失：事务管理可防止崩溃导致进度损失
✅ 类型安全性：修复了NoteMetadata的批处理参数类型

重大变更:

⚠️ indexOnStartup 增强的：现在接受字符串值("auto", "always", "never")除了布尔值（向后兼容）
⚠️ 默认值已更改: indexOnStartup 现在默认为 "auto" 而不是 false

迁移:

旧配置 true/false 仍然有效（映射到 "always"/"never")
推荐：更新至 "auto" 为了获得最佳体验
删除旧索引：如果v1.3的索引不完整，请删除 .mcp-vector-store/ 并让v1.4通过并行处理进行重建

v1.3.0（2025年10月）-自动索引更新

新功能:

✅ 自动文件监视：音符变化时实时矢量索引更新（chokidar）
✅ 取消公告重新索引：智能2秒延迟可防止过度重建
✅ 无缝集成：无需手动重新索引

重大变更:

⚠️ 配置属性已重命名: autoIndex → indexOnStartup （更好地反映了它只控制服务器启动时的初始索引，而不是自动文件监视）

v1.2.0（2025年10月）-矢量搜索和写入操作

新功能:

✅ 语义搜索 使用矢量嵌入（Transformers.js）
✅ 写入操作：创建、更新和删除笔记
✅ 混合搜索：结合语义和关键字搜索（60/40权重）
✅ 增量索引：跟踪文件修改以实现高效更新
✅ 本地嵌入：隐私优先，使用本地Transformers.js模型

错误修复:

✅ 修复了加载config.json时使用脚本目录而不是CWD的问题
✅ 固定了非数组frontmatter标签的标签处理
✅ 改进了对格式错误的YAML frontmatter的错误处理

演出:

✅ 使用5457纸币库进行测试（5456已成功索引）
✅ 快速启动，可选自动索引
✅ 基于Vectra的本地矢量存储（无需外部服务器）

v1.0.0（2025年1月）-生产发布

建筑:

✅ 仅搜索工具设计（无资源预注册）
✅ 快速启动（<1秒）
✅ 可扩展到任何大小的保险库

安全:

✅ 已更新所有依赖关系（0个漏洞）
✅ ESLint 9.17.0，Rimraf 6.0.1，TypeScript ESLint 8.18.2
✅ 消除了存在内存泄漏风险的弃用软件包

MCP-SDK:

✅ 已迁移到MCP SDK 1.20+API
✅ 更新自旧 registerResourceList/registerResource 方法
✅ 干净的TypeScript编译（0个错误）

测试:

✅ 已通过5453纸币保险库验证
✅ 在Windows 11上使用Node.js 25.0.0进行测试
✅ 已确认克劳德桌面集成

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！拜托：

遵循现有代码样式
为新功能添加测试
更新文档
遵循MCP最佳实践

参考文献

建于❤️ 黑曜石+克劳德社区

使用说明

黑曜石MCP服务器

概述

特性

快速开始

先决条件

安装

配置

初始索引（大型保险库需要）

Claude桌面集成

视窗

macOS

多保险库设置

重新启动克劳德桌面

文档

用法

克劳德对话

可用工具

黑曜石_列表_结果

黑曜石搜索结果

黑曜石浪漫搜索

黑曜石read_note

黑曜石创造笔记

黑曜石_更新_注释

黑曜石_delete_note

可用资源

建筑

设计理念

组件图

组件

安全

路径验证

只读模式

输入消毒

发展

构建

开发模式（热重载）

掉毛

测试

故障排除

服务器未启动

Claude找不到服务器

搜索未返回任何结果

权限错误

配置选项

演出

优化策略

建议限值

未来的增强功能

MCP协议合规性

更新日志

v2.0.0（2025年1月）-多保险库支持

v1.4.0（2025年12月）-并行批处理和智能自动索引

v1.3.0（2025年10月）-自动索引更新

v1.2.0（2025年10月）-矢量搜索和写入操作

v1.0.0（2025年1月）-生产发布

许可证

贡献

参考文献

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议

文档搜索服务

Obsidian笔记搜索服务