obsidian-mcp-server

🚀 Obsidian MCP 服务器

Obsidian MCP 服务器是基于 Model Context Protocol 的功能模块，可在 Obsidian 的 vault 中实现强大的文件与内容管理能力。借助调用工具资源，它能执行复杂的文本处理和内容操作。

🚀 快速开始

Obsidian MCP 服务器能助力开发者在 Obsidian vault 中实现复杂的文本处理和文件管理。下面为你介绍其安装与配置步骤。

✨ 主要特性

文件管理

• 列表文件：可列出 vault 中指定目录或根目录下的所有文件。
• 读取文件内容：返回指定路径的文件内容。
• 创建/更新文件：支持原子操作，保障文件写入过程安全可靠。

内容搜索

• 简单文本搜索：在指定文件中查找关键词，并返回上下文内容。
• 复杂搜索（JsonLogic）：依据自定义的 JsonLogic 表达式筛选文件和目录。
• 标签管理：获取 vault 或特定目录中的所有标签信息。

属性管理

• 查询文件属性：获取指定文件的元数据，涵盖标题、作者、类型等。
• 更新文件属性：支持自定义字段更新，自动维护时间戳字段。

📦 安装指南

安装 MCP 服务器

npm install obsidian-mcp-server

配置 MCP 服务器

1. 在 package.json 中添加如下配置：

"mcp_server": {
  "vault_root": "./vault",  // 指定 vault 根目录路径
  "port": 3001,             // 可选，默认端口为 3001
  "log_level": "info"       // 可选，日志级别：debug、info、warning、error
}

2. 启动服务器

npm start

另一种安装与配置方式

1. 克隆仓库 首先，从 GitHub 仓库下载代码：

git clone https://github.com/mcptoolkit/obsidian-mcp-server.git

2. 安装依赖 使用 npm 安装项目所需的依赖包：

cd obsidian-mcp-server
npm install

3. 配置服务器参数 在 config.json 文件中填写以下信息：

{
  "vault_root": "./vault",  // 指定 vault 根目录
  "port": 3001,             // 可选，默认端口为 3001
  "log_level": "info"       // 可选，日志级别：debug、info、warning、error
}

4. 启动服务器 运行以下命令启动 MCP 服务器：

npm start

💻 使用示例

基础用法

文件管理

// 列出指定目录下的文件
const result = await client.call("obsidian_list_files_in_dir", { dirpath: "./" });
console.log(result);

// 读取文件内容
const content = await client.call("obsidian_get_file_contents", { filepath: "notes/README.md" });
console.log(content);

内容搜索

// 简单文本搜索
const result = await client.call("obsidian_find_in_file", {
  filepath: "notes/index.md",
  query: "hello"
});
console.log(result);

// 复杂搜索（JsonLogic）
const result = await client.call("obsidian_complex_search", {
  query: "{ \"and\": [\n" +
         "  { \"glob\": [\"docs/*.md\", { \"var\": \"path\" } ] },\n" +
         "  { \"in\": [=\"#todo\", { \"var\": \"frontmatter.tags\" } ] }\n" +
         "] }"
});
console.log(result);

属性管理

// 查询文件属性
const metadata = await client.call("obsidian_get_file_metadata", { filepath: "notes/todo.md" });
console.log(metadata);

// 更新文件属性
const result = await client.call("obsidian_update_file_properties", {
  filepath: "notes/todo.md",
  properties: {
    priority: "high",
    due_date: "2024-03-15"
  }
});
console.log(result);

高级用法

自动化文件归档

通过设置定时任务，定期调用 MCP 服务器的 obsidian_list_files_in_dir 和 obsidian_move_file 接口，将指定目录下的文件按日期归档。

const { DateTime } = require('luxon');

async function archiveOldFiles() {
  const today = DateTime.local().toISODate();
  const files = await client.call("obsidian_list_files_in_dir", { dirpath: "./old" });
  
  for (const file of files) {
    if (file.lastModified < today) {
      await client.call("obsidian_move_file", {
        from_path: `old/${file.name}`,
        to_path: `archived/${today}/${file.name}`
      });
    }
  }
}

setInterval(archiveOldFiles, 86400000); // 每天执行一次

内容自动分类

结合自然语言处理工具，定期分析文件内容并自动分类。

async function autoCategorize() {
  const files = await client.call("obsidian_list_files_in_dir", { dirpath: "./notes" });
  
  for (const file of files) {
    const content = await client.call("obsidian_get_file_contents", { filepath: `notes/${file.name}` });
    const category = getCategoryFromContent(content);
    
    if (category) {
      await client.call("obsidian_move_file", {
        from_path: `notes/${file.name}`,
        to_path: `${category}/${file.name}`
      });
    }
  }
}

setInterval(autoCategorize, 604800000); // 每周执行一次

📚 详细文档

工具接口

文件操作工具

// 列出 vault 中的所有文件
obsidian_list_files_in_vault: {
}

// 列出指定目录下的文件
obsidian_list_files_in_dir: {
  dirpath: string; // 相对于 vault 根目录的路径
}

// 获取文件内容
obsidian_get_file_contents: {
  filepath: string; // 相对于 vault 根目录的路径
}

搜索操作工具

// 在文件中查找文本并返回上下文
obsidian_find_in_file: {
  query: string,
  contextLength?: number  // 默认上下文长度为10
}

// 使用 JsonLogic 表达式进行复杂搜索
obsidian_complex_search: {
  query: JsonLogicQuery
  // 示例：
  // 按标签查找："{"in": ["#mytag", {"var": "frontmatter.tags"}]}"
  //
  // 按目录查找："{"glob": ["docs/*.md", {"var": "path"}]}"
  //
  // 组合条件："{"and": [
  //   {"glob": ["*.md", {"var": "path"}]},
  //   {"in": ["#mytag", {"var": "frontmatter.tags"}]}
  // ]}'
}

内容修改工具

// 追加内容到文件末尾
obsidian_append_content: {
  filepath: string,  // 相对于 vault 根目录的路径
  content: string    // 要追加的内容
}

// 替换文件内容
obsidian_patch_content: {
  filepath: string,  // 相对于 vault 根目录的路径
  content: string    // 新的内容
}

属性管理工具

// 获取文件元数据
obsidian_get_file_metadata: {
  filepath: string   // 相对于 vault 根目录的路径
}

// 更新文件属性
obsidian_update_file_properties: {
  filepath: string,  // 相对于 vault 根目录的路径
  properties: {      // 需要更新的属性
    [key: string]: any
  }
}

最佳实践

1. 配置管理：确保正确配置 vault_root 和日志级别，以便服务器正常运行。
2. 事务控制：对于涉及文件修改的操作，建议使用事务包裹，确保数据一致性。
3. 权限控制：根据实际需求设置访问控制策略，防止未授权操作。

资源

• 官方文档：Obsidian MCP Server 文档
• 示例代码：GitHub 示例仓库

贡献指南

1. 问题反馈：如有发现任何问题或漏洞，请在 Issues 中提交。
2. 功能建议：欢迎提出功能增强或优化的建议，我们会认真考虑每个合理的需求。
3. 开源贡献：项目基于 MIT 协议开源，欢迎 fork 仓库并提交 PR，共同完善这个工具。

常见问题

1. 如何处理大文件？：对于大文件，建议分块处理或使用流式传输来提高效率。
2. 服务器性能不足怎么办？：可以通过优化代码、增加内存或使用更高效的算法来提升性能。如果单机无法承担负载，可以考虑分布式部署。
3. 如何保证数据一致性？：在进行文件操作时，建议使用事务机制，确保每个操作要么完全成功，要么完全失败，从而维护数据的一致性。

🔧 技术细节

Obsidian MCP 服务器基于 Model Context Protocol 构建，通过调用该协议的接口，实现了在 Obsidian vault 中的文件和内容管理功能。服务器使用 Node.js 开发，借助 npm 进行依赖管理。在配置方面，可通过 package.json 或 config.json 文件指定 vault 根目录、端口和日志级别等参数。在文件操作上，支持原子操作，保证文件写入的安全性；在内容搜索方面，提供了简单文本搜索和基于 JsonLogic 的复杂搜索功能；在属性管理方面，可查询和更新文件的元数据。

📄 许可证

项目基于 MIT 协议开源。