Obsidian MCP 服务器

提供安全、直接访问Obsidian保险库文件系统的MCP服务器。

为什么选择这个服务器？

大多数现有的Obsidian MCP服务器依赖于Obsidian REST API插件，这需要：

• 安装Obsidian
• 运行Obsidian
• 配置REST API插件

而此服务器直接与磁盘上的Obsidian保险库文件交互，使其兼容使用obsidian.nvim的设置——这是一个Neovim插件，无需安装Obsidian应用即可提供类似的功能。

特性

• 直接文件系统访问到Obsidian保险库文件——无需Obsidian应用
• 以安全为中心的设计，防止路径遍历并进行输入验证
• 高性能，带有执行时间跟踪和资源限制
• 丰富的搜索能力，包括正则表达式支持和基于标签的搜索
• 元数据支持，解析前置元数据和内联标签
• MCP资源，用于HATEOAS风格的发现和导航

最近更新

🎉 新特性

• 🗺️ MOC 发现：新的discover-mocs工具提供了对您保险库知识结构的高层次地图，通过发现内容地图及其关系。从这里开始，导航速度提升10倍！
• 资源链接：搜索结果现在包含MCP资源链接，可以直接访问笔记
• 搜索结果中的上下文片段：搜索结果现在包含匹配周围的行，以便更好地理解上下文
• 匹配高亮：搜索词在结果中用粗体标记
• 改进的搜索结果结构：结果现在按文件分组，并附带匹配计数和片段

安装

npm install

使用方法

使用MCP Inspector进行测试

# 将/home/decoder/dev/obsidian/decoder替换为您自己的保险库路径
npx @modelcontextprotocol/inspector node src/index.js /home/decoder/dev/obsidian/decoder

Inspector将在http://localhost:5173打开。

运行测试

# 运行所有测试
npm test

# 在监视模式下运行测试
npm run test:watch

# 运行带有覆盖率报告的测试
npm run test:coverage

# 运行带有覆盖率检查阈值的测试
npm run coverage

# 运行变异测试（所有文件）
npm run test:mutation

# 运行变异测试（仅限分页代码——更快）
npm run test:mutation-pagination

添加到Claude Desktop

要将此服务器添加到Claude Desktop，请使用Claude CLI：

# 克隆此仓库
git clone https://github.com/Piotr1215/mcp-obsidian.git
cd mcp-obsidian

# 安装依赖项
npm install

# 添加到Claude（将/path/to/your/vault替换为您的Obsidian保险库路径）
claude mcp add obsidian -s user -- node /path/to/mcp-obsidian/src/index.js /path/to/your/vault

例如，如果您将仓库克隆到了~/dev/mcp-obsidian，并且您的保险库位于~/Documents/ObsidianVault：

claude mcp add obsidian -s user -- node ~/dev/mcp-obsidian/src/index.js ~/Documents/ObsidianVault

这将把服务器添加到您的Claude配置文件中（通常为~/.claude.json或~/.config/Claude/claude_desktop_config.json）。

要验证安装：

claude mcp list

您应该看到可用的MCP服务器列表中有obsidian。

可用工具

search-vault

跨所有笔记搜索内容。

特性：

• 布尔运算符：AND, OR, NOT（也支持&&, ||, -）
• 字段指定符：title:term, content:term, tag:term
• 引用短语："exact phrase"
• 括号分组：(term1 OR term2) AND term3
• 大小写敏感/不敏感搜索
• 上下文片段：查看每个匹配周围的行
• 匹配高亮：搜索词在结果中用粗体标记
• 资源链接：结果包含MCP资源链接，可直接访问笔记
• 返回按文件分组的结果，附带匹配计数
• 可选路径过滤

上下文选项：

• includeContext（默认：true） - 显示周围行
• contextLines（默认：2） - 匹配前后行数（0-1-10）

示例：

• readme AND install - 查找包含两个词的笔记
• title:setup OR tag:documentation - 根据标题或标签查找
• "getting started" -deprecated - 精确短语，排除已废弃
• (python OR javascript) AND tutorial - 使用括号分组的复杂查询

示例输出带上下文：

{
  "files": [{
    "path": "notes/dotfiles.md",
    "matchCount": 3,
    "matches": [{
      "line": 42,
      "content": "Managing my dotfiles with stow",
      "context": {
        "lines": [
          { "number": 40, "text": "## Configuration Management", "isMatch": false },
          { "number": 41, "text": "", "isMatch": false },
          { "number": 42, "text": "Managing my dotfiles with stow", "isMatch": true },
          { "number": 43, "text": "has simplified my setup process.", "isMatch": false },
          { "number": 44, "text": "", "isMatch": false }
        ],
        "highlighted": "Managing my **dotfiles** with stow"
      }
    }]
  }],
  "totalMatches": 43,
  "fileCount": 15
}

search-by-title

根据H1标题（# 标题）搜索笔记。

• 快速标题搜索
• 大小写敏感/不敏感匹配
• 返回标题、文件路径和行号
• 资源链接：结果包含MCP资源链接，可直接访问笔记
• 可选路径过滤
• 仅匹配H1标题（单个#）

list-notes

列出保险库中的所有Markdown文件或特定目录。

• 返回文件路径和总数
• 资源链接：结果包含MCP资源链接，可直接访问笔记
• 支持目录过滤

read-note

读取特定笔记的完整内容。

• 路径验证确保安全性
• 文件大小限制防止内存问题

write-note

创建或更新具有新内容的笔记。

• 原子写入保证数据完整性
• 自动创建目录
• 内容大小验证

delete-note

从保险库中删除笔记。

• 安全删除，带有适当验证
• 路径安全检查

search-by-tags

查找包含特定标签的笔记。

• 支持YAML前置元数据和内联#标签
• 多个标签的AND操作
• 资源链接：结果包含MCP资源链接，可直接访问笔记
• 大小写敏感/不敏感匹配

get-note-metadata

获取一个或所有笔记的元数据，而不读取完整内容。

• 单笔记模式：获取特定笔记的元数据
• 批量模式：获取保险库中所有笔记的元数据
• 提取前置元数据、标题、标签和内容预览
• 资源链接：结果包含MCP资源链接，可直接访问笔记
• 轻量级替代方案，用于构建笔记索引或仪表板

discover-mocs

⭐ 推荐：从这里开始！ 发现MOCs（内容地图），了解您保险库的知识结构。

内容地图是组织中心笔记（标记为#moc），链接到相关的内容。它们是由Nick Milo提出的灵活替代传统文件夹结构的方法。

特性：

• 列出保险库中的所有MOCs及其链接的笔记
• 展示MOC层次结构（哪些MOCs链接到其他MOCs）
• 显示每个MOC的完整wikilink列表
• 提供对保险库组织的高层次地图
• 10倍快速导航 - 在搜索之前理解结构
• 按MOC名称或目录过滤

为什么使用MOCs？

• 上下文：查看保险库中存在的知识领域
• 规模：了解每个领域的开发程度
• 关系：通过MOC层次结构发现主题之间的联系
• 入口点：找到探索的最佳起点

示例输出：

找到10个MOCs

📚 保险库索引 (24个链接的笔记)
   路径: 00-INDEX.md
   链接: Work-MOC, AI-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Personal-MOC, Homelab-MOC, MCP-Framework-MOC
   🔗 链接到MOCs: Work-MOC, AI-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Personal-MOC, Homelab-MOC, MCP-Framework-MOC

📚 AI-MOC (61个链接的笔记)
   路径: _mocs/AI-MOC.md
   链接: chatgpt, ollama, langchain, aider, gp-nvim, MCP-Framework-MOC, ...
   🔗 链接到MOCs: MCP-Framework-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Work-MOC, 00-INDEX

此工具使代理能够立即理解您的知识图谱结构，使得导航比盲目关键词搜索快约10倍。

MCP资源

此服务器实现了MCP资源支持，用于HATEOAS风格的发现：

• 自动资源链接：所有搜索和列表工具返回资源链接
• 直接笔记访问：使用资源URI读取笔记，无需搜索
• 资源URI格式：obsidian-note://相对路径/到/note.md
• 丰富元数据：资源链接包含标签、标题和匹配计数

示例：当您搜索"MCP"时，结果包含资源链接：

{
  "content": [
    {
      "type": "text",
      "text": "在2个文件中找到5个匹配项，对于\"MCP\""
    },
    {
      "type": "resource_link",
      "uri": "obsidian-note://guides/MCP-Guide.md",
      "name": "MCP实现指南",
      "description": "3个匹配项 | 标签: mcp, guide, development"
    }
  ]
}

代理可以使用资源URI直接读取笔记，从而无缝地浏览您的知识库。

安全特性

此服务器实施了全面的安全措施：

• 路径遍历预防：所有文件路径都经过验证，以防止访问保险库之外的文件
• 输入验证：所有输入都根据JSON模式进行验证
• 文件大小限制：可配置限制防止内存耗尽（默认：10MB）
• 内容净化：移除潜在有害的空字节
• 仅Markdown访问：只能访问.md文件

详情参见MCP_SPEC_COMPLIANCE.md。

贡献

1. 确保所有测试通过：npm test
2. 维护测试覆盖率高于90%：npm run coverage
3. 遵循函数式编程原则
4. 为新功能添加测试
5. 根据需要更新文档