Obsidian MCP Server (TypeScript)

黑曜石MCP服务器（TypeScript）

一个通过本地REST API社区插件与Obsidian交互的TypeScript MCP服务器。

备注：这是原始的TypeScript端口 mcp黑曜岩 MarkusPoundstein的Python项目。所有原创概念和API设计的功劳都归于原作者。

特性

• 🚀 高性能：LRU缓存、请求重复数据删除和优化的批处理
• 🔧 类型安全：具有严格类型和全面错误处理的完整TypeScript
• 📋 动态工具发现：自动发现并加载包含元数据的工具
• 🎯 智能错误处理：简化了错误响应，并提供了可操作的建议
• 📦 模块化架构：将关注点与可重复使用的实用程序彻底分离
• 📊 MCP资源：通过资源协议对vault数据进行只读访问
• 📏 资源元数据：文件大小和上次修改的时间戳，以更好地优化缓存
• ⚠️ 协议兼容错误：用于一致错误处理的标准MCP错误代码

性能优化：内部资源缓存

黑曜石MCP服务器通过智能内部资源缓存自动优化性能。该系统为频繁使用的操作提供了显著的速度改进，同时对用户保持完全透明。

实时缓存同步

该服务器包括一个复杂的订阅系统，当文件更改时，该系统会自动使缓存的数据无效。这可确保您始终看到当前数据，而无需手动清除缓存：

• 自动更新：文件操作（创建、更新、删除）会触发缓存立即失效
• 智能失效：仅清除受影响的缓存，保留无关的缓存数据
• MCP客户端通知：连接的客户端接收实时资源更新通知
• 零配置：订阅系统自动工作，无需设置

有关技术详细信息，请参阅 订阅系统文档.

运作原理

现在，几个主要工具使用内部MCP资源进行智能缓存，而不是每次直接调用API：

用户利益

• 透明性能：所有速度提升都会自动进行，无需配置
• 向后兼容：现有工作流继续以完全相同的方式工作
• 智能失效：当您通过工具修改文件时，缓存会自动更新
• 减少API负荷：减少对Obsidian的REST API的直接调用提高了整体响应能力
• 更好的用户体验：浏览标签、搜索和访问最新文件等操作感觉即时

技术细节

优化工作原理如下：

1. 资源优先战略：工具在进行API调用之前检查内部MCP资源
2. 分层缓存：基于数据波动性的不同缓存持续时间（最近更改为30秒，保险库结构为5分钟）
3. 优雅的后退：如果资源不可用，工具会自动回退到直接调用API
4. 内存效率高：使用带有自动清理功能的LRU缓存来防止内存泄漏

这种优化是我们致力于使黑曜石MCP服务器在日常使用中既强大又高性能的一部分。

MCP资源增强

资源元数据（v2.3.0）

所有MCP资源现在都在 _meta 字段，提供文件大小和修改时间戳，而不需要额外的API调用。这使得客户端能够更好地进行缓存优化和资源管理。

元数据结构

{
  "uri": "vault://note/meeting-notes.md",
  "name": "Meeting Notes",
  "mimeType": "text/plain",
  "text": "# Meeting Notes\n...",
  "_meta": {
    "size": 2048,                           // File size in bytes
    "sizeFormatted": "2.00 KB",             // Human-readable size
    "lastModified": "2025-10-07T14:30:00.000Z"  // ISO 8601 timestamp (UTC)
  }
}

用例

• 缓存验证：使用 lastModified 用于确定缓存资源是否过时的时间戳
• 资源筛选：在获取完整内容之前，按大小筛选资源
• 性能监控：跟踪资源大小以优化批处理操作
• 用户反馈：在UI中显示文件大小和修改日期

故障弱化

这 _meta 字段是可选的。如果无法提取元数据（例如，API错误），则资源仍将在没有元数据的情况下工作。这确保了向后兼容性和可靠性。

符合协议的错误处理

错误处理现在使用标准MCP错误代码进行一致的协议集成：

错误响应示例：

// Before: Tool-specific error format
{
  "success": false,
  "error": "File not found",
  "tool": "obsidian_get_file_contents"
}

// After: MCP protocol-compliant
throw new McpError(
  ErrorCode.MethodNotFound,
  "Resource not found: vault://note/missing.md"
);

这种标准化使所有MCP客户端和工具都能更好地处理错误。

二进制文件支持（MCP4-v2.4.0）

通过相同的统一界面访问图像、PDF、音频和视频文件 vault://note/{path} URI。服务器会自动检测二进制文件，并将其作为base64编码的blob返回。

支持的格式：

• 图片：PNG、JPG、JPEG、GIF、SVG、WebP、BMP、ICO
• 文档：PDF
• 音频：MP3、WAV、OGG、AAC、FLAC、M4A
• 视频：MP4、WebM、MOV、AVI、MKV

工作原理： 服务器会根据扩展名自动检测文件类型，并返回相应的内容：

• 文本文件(.md, .txt)：返回为 TextResourceContents 有降价
• 二进制文件：返回为 BlobResourceContents 使用base64编码数据

示例-访问图像：

// Request an image resource
const imageResource = await client.readResource('vault://note/attachments/diagram.png');

// Response structure for binary files
{
  "uri": "vault://note/attachments/diagram.png",
  "name": "diagram.png",
  "mimeType": "image/png",
  "blob": "iVBORw0KGgoAAAANSUhEUgAA...", // base64-encoded data
  "_meta": {
    "size": 45678,
    "sizeFormatted": "44.61 KB",
    "lastModified": "2025-10-07T14:30:00.000Z"
  }
}

尺寸限制： 为了安全和性能，二进制文件限制为10 MB。超过此限制的文件将返回错误，并建议通过工具访问。

使用案例：

• 显示嵌入笔记中的图像
• 访问PDF附件进行处理
• 提取音频/视频元数据
• 以编程方式下载二进制资产

功能状态

本节显示了Obsidian MCP服务器中可用的资源和功能。

MCP可用资源✅

MCP资源通过资源协议提供对黑曜石保管库数据的只读访问。这些是人工智能助手维护金库上下文的理想选择。

📚 请参阅 完整资源指南 获取详细的文档、示例和最佳实践。

静态资源（缓存5分钟）

动态资源（缓存1-2分钟）

使用资源

通过MCP协议访问资源 resources/list 和 resources/read 方法：

// List available resources
const resources = await client.listResources();

// Read specific resources
const tags = await client.readResource('vault://tags');
const stats = await client.readResource('vault://stats');
const note = await client.readResource('vault://note/meeting-notes.md');
const folder = await client.readResource('vault://folder/Projects');

// Recent changes with preview mode (default)
const recentPreview = await client.readResource('vault://recent');
// Returns: { notes: [{ path, title, modifiedAt, preview }], mode: 'preview' }

// Recent changes with full content 
const recentFull = await client.readResource('vault://recent?mode=full');
// Returns: { notes: [{ path, title, modifiedAt, content }], mode: 'full' }

资源与工具决策

• 资源：只读数据访问、缓存响应、AI在上下文中需要的参考信息
• 工具：修改内容、实时操作、一次性查询的操作

工作流程示例：使用 vault://tags 查看可用标签的资源→ Use obsidian_get_files_by_tag 查找特定文件的工具→ Use vault://note/{path} 读取这些文件的资源。

工具

服务器实现了多种与黑曜石交互的工具：

• list_files_in_vault：列出黑曜石保管库根目录中的所有文件和目录
• list_files_in_dir：列出特定黑曜石目录中的所有文件和目录（现在为空目录返回空数组，而不是错误）
• find_empty_directions：通过扫描目录结构查找vault中的所有空目录
• get_file_contents：返回vault中单个文件的内容
• batch_get_file_contents：返回vault中多个文件的内容，并将其与标头连接起来
• simple_search：在vault中的所有文件中简单搜索与指定文本查询匹配的文档
• advanced_search：使用结构化过滤器对内容、元数据、标签和frontmatter进行高级搜索（推荐）
• complex_search:使用JsonLogic查询进行复杂搜索-需要对JsonLogic运算符的Obsidian REST API支持
• obsidian_edit：通过智能操作编辑黑曜石金库笔记-从简单的附加到结构化编辑的渐进式复杂性
• simple_append：简单的文本附加到文件-可靠的基本添加
• simple_replace：简单的查找和替换操作-直接的文本替换
• query_structure：查询文档结构以获取标题、块和节，这对于LLM在修改内容之前构建明确的引用非常有用
• append_content：将内容附加到vault中的新文件或现有文件
• delete_file：从vault中删除文件或目录
• rename_file:重命名同一目录中的文件，同时保留历史记录和更新链接（需要更新的REST API插件）
• move_file：将文件移动到不同的位置（可以在目录之间移动、就地重命名或同时在两者之间移动），同时保留历史记录和更新链接（需要更新的REST API插件）
• move_directory：将整个目录及其所有内容移动到不同的位置，同时保留内部结构并更新所有链接
• copy_file：将文件复制到vault中的新位置，创建一个保留所有内容的副本
• copy_directory：将整个目录及其所有内容复制到新位置，保留内部结构
• check_path_exists：检查vault中是否存在文件或目录，并确定其类型
• create_directory：在vault中创建一个新目录，支持创建嵌套目录结构
• delete_directory：从vault中删除目录，可选递归删除内容
• get_all_tags：列出vault中所有唯一的标签及其使用计数
• get_files_by_tag：获取包含特定标记的所有文件
• rename_tag：重命名整个vault中的标记
• manage_file_tags：在特定文件中添加或删除标签（批处理操作-多个标签的速度快10x-100倍）
• get_periodic_note：获取指定期间（每日、每周、每月、每季度、每年）的当前周期注释
• get_recent_periodic_notes：获取指定周期类型的最新周期注释
• get_recent_changes:获取vault中最近修改的文件（注意：API尚不支持内容预览参数）
• get_file_metata：在不检索内容的情况下获取文件元数据（大小、日期、权限）-对大文件高效
• get_file_frontmatter：只获取没有内容的文件的前体，这对元数据分析很有效
• get_file_formatted：获取不同格式（纯文本、HTML等）的文件以进行令牌优化

示例提示

最好先指导克劳德使用黑曜石。然后，它将始终调用该工具。

使用提示如下：

• 获取上次架构调用说明的内容并对其进行总结
• 搜索所有提到Azure CosmosDb的文件，并快速向我解释提到它的上下文
• 总结上次会议笔记，并将其放入新笔记“summary meeting.md”中。添加一个介绍，这样我就可以通过电子邮件发送了。
• 将我的文件“draft proposal.md”重命名为“final-proposal-2024.md”
• 替换所有出现的“！\[\[old image.png\]\]'带'！\[\[new image.png\]\]'在我的笔记中
• 在meeting-notes.md中查找“TODO:”并将其替换为“-\[\]”，以转换为复选框
• 将“收件箱/todo.md”移动到“项目/active/todo.md”以重新组织它
• 将所有文件从“收件箱”文件夹移动到“已处理/2024”文件夹
• 将整个“草稿/2023”目录移动到“归档/2023/drafts”以组织旧内容
• 将“templates/meeting template.md”复制到“meetings/2024-07-02-standup.md”以用于今天的会议
• 在创建新文件之前，检查“projects/important project/”目录是否存在
• 创建一个新的目录“项目/2024/q3倡议”，用于组织季度工作
• 删除空的“旧草稿/”目录（默认情况下移动到垃圾箱）
• 使用recursive=true和permanent=true永久删除“temp folder/”及其所有内容
• 将“项目/模板结构/”复制到“项目/新客户/”以重用项目结构
• 列出我保管库中的所有标签，查看哪些标签最常用
• 查找所有标记为#project的文件以查看我的活动项目
• 在我的所有笔记中将标签#todo重命名为#task
• 在今天的会议笔记中添加标签#meeting#important
• 搜索上周修改的包含“API”的文件
• 查找frontmatter字段“状态”等于“进行中”的所有笔记
• 搜索包含正则表达式模式“TODO|FIXME”的大于10KB的markdown文件
• 只获取large-notes.md的元数据，在阅读之前检查其大小
• 仅从meeting-notes.md中提取标题以分析标签和状态
• 以纯文本格式获取今天的每日笔记，无需标记格式
• 检索project-readme.md作为HTML，以便在黑曜石外部共享
• 查找vault中的所有空目录以进行清理
• 仅搜索“存档”文件夹中的空目录
• 在“projects/drafts/”中列出文件-如果目录为空，将返回空数组

编辑工具概述

MCP服务器为编辑黑曜石笔记提供了越来越复杂的工具：

简单的操作

• obsidian_simple_append -使用自动换行处理将文本附加到文件
• obsidian_simple_replace -查找和替换文件中的文本

智能编辑

• obsidian_edit -具有渐进复杂性的统一编辑工具：

- 第一阶段：简单的追加操作（100%可靠性） - 第二阶段：结构感知编辑（在标题前后插入） - 第3阶段：复杂操作（批量编辑、新部分）

结构查询

• obsidian_query_structure -编辑前查询文档结构以查找标题和块

使用示例：

// Simple append
await obsidian_simple_append({
  filepath: "note.md",
  content: "New paragraph"
});

// Smart editing - insert after heading
await obsidian_edit({
  file: "note.md",
  after: "Overview",
  add: "New content after the Overview heading"
});

// Find and replace
await obsidian_simple_replace({
  filepath: "note.md",
  find: "old text",
  replace: "new text"
});

// Complex batch operations
await obsidian_edit({
  file: "note.md",
  batch: [
    { after: "Introduction", add: "New intro content" },
    { find: "TODO", replace: "DONE" }
  ]
});

请参阅 迁移指南 了解详情。

工具类别

为了更好地发现，工具被分为不同的类别：

• 文件操作：读取、写入、复制、移动文件
• 目录操作：创建、删除、移动目录
• 搜索：简单而高级的搜索功能
• 编辑：具有结构感知的智能内容编辑
• 标签：标签管理和操作
• 定期注意事项：每日、每周、每月票据支持

配置

配置概述

黑曜石MCP服务器通过按优先级顺序检查多个源的分层系统支持灵活的配置。这允许您以最适合您的工作流程的方式配置服务器。

配置层次结构

服务器按顺序从这些源加载配置（较高优先级覆盖较低优先级）：

1. 环境变量 （最高优先级）

- OBSIDIAN_API_KEY -您的Obsidian REST API密钥 - OBSIDIAN_HOST -黑名单REST API主机（默认值： 127.0.0.1) - OBSIDIAN_CONFIG_FILE -自定义配置文件的路径

1. 配置文件 （建议用于持久设置）

- 默认位置： ~/.config/mcp/obsidian.json - 通过自定义位置 OBSIDIAN_CONFIG_FILE 环境变量

1. 默认值 （最低优先级）

- 主持人： 127.0.0.1 - 端口： 27124 （黑眼圈REST API默认设置）

配置方法

方法1：环境变量

最适合：临时会话、测试、CI/CD环境

# Set API key (required)
export OBSIDIAN_API_KEY=your_api_key_here

# Set custom host (optional, defaults to 127.0.0.1)
export OBSIDIAN_HOST=192.168.1.100

# Use custom config file location (optional)
export OBSIDIAN_CONFIG_FILE=/path/to/your/config.json

方法2：配置文件

最适合：持久设置、多个保管库、共享配置

默认位置: ~/.config/mcp/obsidian.json

{
  "apiKey": "your_api_key_here",
  "host": "127.0.0.1"
}

自定义位置：通过环境变量设置

export OBSIDIAN_CONFIG_FILE=/path/to/your/custom-config.json

方法3:Claude桌面配置

最适合：希望将所有配置放在一个地方的Claude Desktop用户

{
  "mcpServers": {
    "obsidian-mcp-ts": {
      "command": "npx",
      "args": ["obsidian-mcp-ts"],
      "env": {
        "OBSIDIAN_API_KEY": "your_api_key_here",
        "OBSIDIAN_HOST": "127.0.0.1"
      }
    }
  }
}

配置优先级示例

示例1：环境变量覆盖配置文件

# Config file has apiKey: "file-key"
export OBSIDIAN_API_KEY="env-key"
# Server will use "env-key"

示例2：使用自定义主机的配置文件

// ~/.config/mcp/obsidian.json
{
  "apiKey": "your-key",
  "host": "10.0.0.5"
}

示例3：自定义配置文件位置

export OBSIDIAN_CONFIG_FILE=/home/user/vault-configs/work-vault.json

查找您的API密钥

1. 开放式黑曜石
2. 转到“设置”→ 社区插件
3. 找到“本地REST API”并单击齿轮图标
4. 从插件设置中复制API密钥

安全最佳实践

1. 永远不要提交API密钥 到版本控制
2. 使用配置文件 而不是持久设置的环境变量
3. 设置适当的权限 在配置文件上：

   chmod 600 ~/.config/mcp/obsidian.json

1. 使用不同的API密钥 尽可能使用不同的保险库

配置问题疑难解答

如果服务器找不到您的API密钥，它将显示：

OBSIDIAN_API_KEY not found. Please provide it via:
1. OBSIDIAN_API_KEY environment variable
2. Config file at ~/.config/mcp/obsidian.json
3. Custom config file via OBSIDIAN_CONFIG_FILE environment variable

常见问题：

• 权限不足：检查您的API密钥是否正确
• 连接失败：验证Obsidian正在运行并且已启用REST API插件
• 文件未找到：确保配置文件路径是绝对的，而不是相对的

快速设置

使用提供的设置脚本进行交互式配置：

./setup-config.sh

或者手动使用配置模板 obsidian-config-template.json:

cp obsidian-config-template.json ~/.config/mcp/obsidian.json
# Edit the file and replace YOUR_OBSIDIAN_API_KEY_HERE with your actual key

高级配置

有关详细的配置选项、多个vault设置和故障排除，请参阅 配置指南.

快速入门

安装

从npm安装

npm install -g obsidian-mcp-ts

黑眼圈REST API

您需要运行Obsidian REST API社区插件：https://github.com/coddingtonbear/obsidian-local-rest-api

在设置中安装并启用它，然后复制api密钥。

克劳德桌面版

在MacOS上： ~/Library/Application\ Support/Claude/claude_desktop_config.json

在Windows上： %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

{
  "mcpServers": {
    "obsidian-mcp-ts": {
      "command": "node",
      "args": [
        "
/obsidian-mcp-ts/dist/index.js"
      ],
      "env": {
        "OBSIDIAN_API_KEY": ""
      }
    }
  }
}

Published Servers Configuration

{
  "mcpServers": {
    "obsidian-mcp-ts": {
      "command": "npx",
      "args": [
        "obsidian-mcp-ts"
      ],
      "env": {
        "OBSIDIAN_API_KEY": ""
      }
    }
  }
}

Using External Config File (Recommended)

首先，在以下位置创建配置文件 ~/.config/mcp/obsidian.json:

{
  "apiKey": "your-obsidian-api-key-here",
  "host": "127.0.0.1"
}

然后在Claude Desktop配置中，您只需要：

{
  "mcpServers": {
    "obsidian-mcp-ts": {
      "command": "npx",
      "args": ["obsidian-mcp-ts"]
    }
  }
}

服务器将自动从配置文件加载API密钥。您还可以使用自定义配置位置：

{
  "mcpServers": {
    "obsidian-mcp-ts": {
      "command": "npx",
      "args": ["obsidian-mcp-ts"],
      "env": {
        "OBSIDIAN_CONFIG_FILE": "/path/to/your/config.json"
      }
    }
  }
}

错误处理

MCP服务器使用简化的错误格式进行清晰一致的错误报告：

错误响应结构

所有错误都遵循以下结构：

{
  success: false,
  error: string,        // Error message
  tool: string,         // Tool name that generated the error
  suggestion?: string,  // Optional actionable suggestion
  example?: object      // Optional example of correct usage
}

常见错误类型

1. 找不到文件（404）

   {
     "success": false,
     "error": "File not found: notes/missing.md",
     "tool": "obsidian_get_file_contents",
     "suggestion": "Use obsidian_list_files_in_vault to browse available files first"
   }

1. 身份验证失败（401）

   {
     "success": false,
     "error": "Authentication failed - check API key",
     "tool": "obsidian_list_files_in_vault",
     "suggestion": "Verify your OBSIDIAN_API_KEY is correct in Claude Desktop settings"
   }

1. 无效参数

   {
     "success": false,
     "error": "Missing required parameters",
     "tool": "obsidian_append_content",
     "suggestion": "Provide both filepath and content parameters",
     "example": {
       "filepath": "notes/example.md",
       "content": "New content to append"
     }
   }

错误恢复

当您遇到错误时：

1. 检查 suggestion 立即修复的字段
2. 使用 example 字段以了解正确的参数格式
3. 对于文件操作，请使用验证文件是否存在 obsidian_list_files_in_vault
4. 有关身份验证错误，请检查API密钥配置

发展

建筑

准备分发包裹：

1. 安装依赖项：

npm install

1. 构建TypeScript代码：

npm run build

测试

运行测试套件：

# Run all tests
npm test

# Run integration tests (requires compiled code)
npm run build
npm run test:integration

# Run E2E tests against real Obsidian API
OBSIDIAN_API_KEY=your-key npm run test:e2e

# Run tests in watch mode during development
npm run test -- --watch

调试

由于MCP服务器在stdio上运行，调试可能具有挑战性。为了达到最佳调试效果 经验，我们强烈建议使用 MCP检查员.

您可以通过以下方式启动MCP检查器 使用此命令：

# For development (with TypeScript)
npx @modelcontextprotocol/inspector tsx src/index.ts

# For production (compiled)
npx @modelcontextprotocol/inspector node dist/index.js

启动后，检查器将显示一个URL，您可以在浏览器中访问该URL以开始调试。

您还可以使用以下命令查看服务器日志：

tail -n 20 -f ~/Library/Logs/Claude/mcp-server-obsidian-mcp-ts.log

开发命令

# Run in development mode with auto-reload
npm run dev

# Type check without building
npm run typecheck

# Build for production
npm run build

# Run the built server
npm start

# Lint code
npm run lint

性能优化

服务器包括几个性能优化：

• LRU缓存：减少对频繁访问数据的API调用
• 请求重复数据删除：防止重复的并发请求
• 优化批处理：具有重试逻辑的智能并发控制
• 流媒体结果：处理大型数据集，无需将所有内容加载到内存中

性能基准

比较缓存操作和非缓存操作，以了解缓存何时有益：

# Run comprehensive benchmark test
npm test -- tests/benchmarks/cached-vs-noncached.benchmark.test.ts

# Quick standalone benchmark
npx tsx scripts/run-cache-benchmark.ts --scenario sequential

# Test with different configurations
npx tsx scripts/run-cache-benchmark.ts --iterations 100 --data-size 10240

基准测试测试了六种情况：

• 顺序访问：命中率高（90-98%），速度提高10-50x✅
• 80/20图案：真实使用（命中率70-85%），3-8倍加速✅
• 随机访问：命中率低（10-30%），边际效益⚠️
• 唯一访问：无缓存优势（0%命中率），禁用缓存❌

看 缓存性能基准 以获取详细的分析和配置指南。

看 性能最佳实践 详细的优化策略。

建筑

代码库遵循干净的架构原则：

• 工具：每个工具都是一个包含元数据的自包含类
• 公用事业：可重用组件（缓存、批处理程序、错误处理程序）
• 常量：集中配置值
• 类型：为所有操作提供全面的TypeScript类型

工具在运行时动态发现，使添加新功能变得容易。