AI导哈

Obsidian知识库管理服务

将Obsidian知识库转化为结构化上下文源，为Claude Desktop等LLM工具提供高效的知识管理功能。

  • by nbaradar
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 nbaradar/obsidian-mcp-server

使用说明

🧠 黑曜石MCP服务器

将您的黑曜石库转换为Claude Desktop的结构化上下文源

📚 技术深度潜水： 阅读完整的开发历程 --研究笔记、设计决策和迭代历史。

为什么存在

黑曜石拱顶是我的知识所在。但是，将它们连接到LLM需要的不仅仅是“读取文件”，您还需要 vault感知会话, 基于航向的导航，以及 令牌高效搜索 这不会破坏你的上下文窗口。

此MCP服务器通过将黑曜石保险库视为 一流数据源 对于LLM，使用围绕markdown实际工作原理设计的工具（基于结构，而不是基于行号）。

✨ 主要特点

🗂️ 多保险库会话管理

  • 在中配置多个保管库 vaults.yaml （个人、工作、研究等）
  • 在对话中切换活动保险库： “使用我的工作保险库”
  • 跨工具调用的会话感知上下文跟踪

🎯 结构感知编辑

传统的文件操作使用行号。Markdown使用 标题.

## Project Ideas
Some content here

### Idea 1
Details about idea 1

## Resources
Links and references

使用此服务器：

  • insert_after_heading("Project Ideas") → 在正确的语义位置添加内容
  • replace_section("Idea 1") → 仅更新该小节
  • delete_section("Resources") → 删除标题+所有内容，直到下一个相同级别的标题

🔍 代币高效搜索

搜索10条内容完整的笔记： 约50000个代币 💸
使用上下文片段搜索： 约1500个代币 ✅

# Returns 3 snippets per match, ~200 chars each
search_obsidian_content("MCP server design patterns")

克劳德获得了足够的上下文来理解比赛，而不会消耗你的代币预算。

🏷️ 前线指挥控制

  • 读取、合并、替换或删除YAML frontmatter，而无需触摸笔记正文
  • 强制模式验证（大小限制、UTF-8、YAML安全类型）
  • 专为标签管理和模板验证等未来自动化而设计

🚀 快速开始

先决条件

安装

# Clone the repository
git clone https://github.com/nbaradar/obsidian-mcp-server.git
cd obsidian-mcp-server

# Install dependencies with uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

配置

  1. 创建 vaults.yaml 在项目根目录中：
default: personal
vaults:
  personal:
    path: "/Users/you/Documents/PersonalVault"
    description: "Primary personal vault"
  
  work:
    path: "/Users/you/Documents/WorkVault"
    description: "Work projects and documentation"
  1. 添加到Claude桌面配置 (~/Library/Application Support/Claude/claude_desktop_config.json):
{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": [
        "/absolute/path/to/obsidian-mcp-server/server.py"
      ]
    }
  }
}
  1. 重新启动克劳德桌面

你应该看看”🔌 使用您的黑曜石工具在Claude Desktop中创建“MCP”。

🎬 它看起来像什么

配置后，您将在Claude Desktop中看到您的黑曜石工具：

22种工具可用于多保险库笔记管理，具有标题感知操作

此外，您也可以使用您偏好的MCP客户端！在这里，我在代理模式下使用VSCode和Copilot。
关于如何将VSCode连接到MCP的更多细节， 查看这里

您甚至可以将其与您自己的本地LLM模型一起使用！我在这里跑步 qwen3-14b 使用 LM 工作室

📖 用法示例

基本操作

User: "Create a note called 'Project Ideas' in my personal vault"
Claude: [uses create_obsidian_note]

User: "Switch to my work vault and list all notes"
Claude: [uses set_active_vault, then list_obsidian_notes]

User: "Search for notes about 'machine learning'"
Claude: [uses search_obsidian_content for snippets]

高级：结构化编辑

User: "In my 'Meeting Notes' file, add today's standup under the 'Daily Standups' heading"
Claude: [uses insert_after_heading_obsidian_note]

User: "Replace the 'Action Items' section with..."
Claude: [uses replace_section_obsidian_note]

User: "Add a summary paragraph at the end of 'Project Updates' before any subsections"
Claude: [uses append_to_section_obsidian_note]

User: "What’s the most recent note in my Mental Health folder?"
Claude: [uses list_notes_in_folder("Mental Health", include_metadata=True, sort_by="modified")]

🛠️ 可用工具

管理

工具 目的
list_vaults 发现已配置的保管库和当前会话状态
set_active_vault 切换活动保险库以进行后续操作

核心业务

工具 目的
create_obsidian_note 创建新的markdown文件
retrieve_obsidian_note 阅读完整笔记内容
replace_obsidian_note 覆盖整个文件
append_to_obsidian_note 将内容添加到末尾
prepend_to_obsidian_note 将内容添加到开头
delete_obsidian_note 删除文件
move_obsidian_note 移动或重命名注释（可选反向链接更新）

结构化编辑

工具 目的
insert_after_heading_obsidian_note 在标题下方插入内容
append_to_section_obsidian_note 将内容附加到子章节之前的标题部分
replace_section_obsidian_note 替换标题下的内容
delete_section_obsidian_note 删除标题及其部分

前台

工具 目的
read_obsidian_frontmatter 仅返回YAML frontmatter块
update_obsidian_frontmatter 将字段合并到现有frontmatter中
replace_obsidian_frontmatter 覆盖整个frontmatter块
delete_obsidian_frontmatter 完全拆除前体块

发现

工具 目的
list_obsidian_notes 列出所有注释，可选择包括元数据
search_obsidian_notes 搜索笔记标题（支持元数据+排序）
list_notes_in_folder 目标文件夹列表（元数据+递归支持）
search_obsidian_content 令牌高效内容搜索
search_notes_by_tag 基于标记的令牌高效搜索

按需元数据： list_obsidian_notes, search_obsidian_notes，以及 list_notes_in_folder 接受 include_metadata=True 附加ISO时间戳和文件大小。旗帜大致加起来 每张纸币9个代币，因此请在广泛的列表中禁用它，并在需要“最新”时启用它 或“最大音符”风格的查询。

🧭 内部架构

从v1.4.3开始，代码库使用 模块化封装结构 为了更好的可维护性和可测试性：

obsidian_vault/
├── core/                    # Pure business logic (NO MCP dependencies)
│   ├── vault_operations.py       # Path validation and sandboxing
│   ├── note_operations.py        # Note CRUD operations
│   ├── search_operations.py      # Search and discovery
│   ├── section_operations.py     # Heading-based manipulation
│   └── frontmatter_operations.py # YAML frontmatter ops
│
├── tools/                   # MCP tool wrappers (thin layer)
│   ├── vault_tools.py       # Vault management tools
│   ├── note_tools.py        # Note CRUD tool wrappers
│   ├── search_tools.py      # Search tool wrappers
│   ├── section_tools.py     # Section tool wrappers
│   └── frontmatter_tools.py # Frontmatter tool wrappers
│
├── server.py                # FastMCP server initialization
├── config.py                # Configuration loading (vaults.yaml)
├── session.py               # Per-session active vault tracking
└── models.py                # Data models (VaultMetadata, etc.)

主要优势：

  • 关注点分离：核心逻辑与MCP无关，可以独立测试
  • 单一责任：每个模块都有一个明确的目的
  • 可扩展性：通过扩展核心模块、工具包装器自动注册添加新功能
  • 可测试性：核心模块可以在没有MCP服务器基础设施的情况下进行单元测试

数据流：

  1. MCP工具包装器接收请求（处理上下文、vault解析）
  2. 调用相应的核心操作（纯业务逻辑）
  3. 核心操作返回结构化数据
  4. MCP客户端的工具包装器格式响应

🏗️ 设计原则

1. 代币效率优先

每个工具都旨在最大限度地减少上下文窗口的使用：

  • 基于片段的搜索与完整内容检索
  • 在完整文件读取过程中基于标题的导航
  • 通过多个工具调用进行组合操作
任务 天真 此服务器 节省
“在中查找最新笔记 心理健康“ ~60000个代币 ~450个代币 ~99%
“查找最大的文件” ~30万个令牌 ~850个令牌 ~97%

2. Markdown原生操作

传统编辑器使用行号。这与注释编辑无关。 语义锚 （标题）在内容变化时保持稳定。

3. 会话感知上下文

克劳德可以在谈话中在保险库之间切换，而不会失去状态。

4. MCP建筑商合规性

所有工具均遵循 MCP构建器技能 格式--单行摘要→ 解释→ 参数→ 返回模式→ 使用/不使用——使用指导。

5. 日志记录和调试

服务器使用Python logging （stderr/file）用于所有操作：vault开关、CRUD事件、帮助程序调用和错误。

  • 日志存储在 ~/Library/Logs/Claude/ 在Claude Desktop下运行时。
  • 避免 print() --它破坏了STDIO JSON-RPC流。
  • 令牌成本跟踪挂钩（即将推出）将记录每次操作的令牌估计值，以便进行调试。

6. 错误处理原理

优雅、描述性和安全：

  • 缺少注释/路径错误→ 建议正确的工具或路径。
  • YAML格式错误→ 报告确切的行/类型。
  • 保险库或文件系统错误→ 引用配置路径。
  • 破坏性操作总是得到客户的确认。

🧪 测试总结

在多个真实保管库和自动化套件中验证实施。

  • 27个标签搜索测试，涵盖格式处理、不区分大小写、元数据排序、嵌套文件夹、AND/OR语义、性能和异步MCP集成。
  • 4个路径规范化回归测试，确保虚线注释标题、嵌套路径、大写 .MD，遍历拒绝行为如预期。
  • 测试命令： PYTHONPATH=. uv run --with pytest --with pytest-asyncio pytest tests/test_path_normalization.py tests/test_tag_search.py

🌿 前台规则

Frontmatter工具仅在YAML块上运行，以保存令牌并避免不必要的内容重写。

  • 验证UTF-8和YAML安全类型；拒绝格式错误或过大的元数据。
  • 默认情况下合并语义（保留未知键）。
  • 专为未来的标签自动化和模板验证而设计。

🔌 远程访问（计划）

目前运行通过 工作室 （仅限本地）。未来版本将支持 HTTP传输 用于根据MCP规范具有可选身份验证的远程客户端。

🚧 已知限制

  • 目前还没有基于正则表达式或属性/frontmatter的搜索。
  • 没有SQLite索引或缓存。
  • 无图像/附件管理。
  • 无反向链接维护（移动/重命名时的链接更新除外）。
  • 无HTTP传输或身份验证（仅限STDIO）。
  • 从v1.4.2开始，完全支持带圆点的注释标题； _normalize_note_identifier 在执行沙盒规则的同时保留内部段。

🗺️ 路线图

  • [x] v1.0 --核心CRUD操作
  • [x] v1.1 --令牌高效内容搜索
  • [x] v1.2 --基于结构化标题的编辑
  • [x] v1.3 --改进Vault导航
  • [x] v1.4 --前端操纵+标签搜索
  • [x] v1.4.1 --标签搜索工具优化（已完成）
  • [x] v1.4.2 --在中保留虚线注释标识符 _normalize_note_identifier
  • [x] v1.4.3 --重构代码库结构
  • [x] v1.5 --用于输入验证的Pydantic数据模型
  • [ ] v1.6 --Vault感知提示资源
  • [ ] v1.6.1 --Vault特定模板
  • [ ] v2.0 --用于远程访问的HTTP传输

看 AGENTS.md 详细的开发说明和架构决策。

📚 文档

🤝 贡献

该项目正在积极开发中。欢迎投稿、问题和功能请求！

特别感兴趣的是：

  • 在Windows/Linux上进行测试（目前以Mac为重点）
  • 其他保险库来源（Notion、Roam等）
  • 大型金库（10k+纸币）的性能优化

📄 许可证

MIT许可证-请参阅 许可证 了解详情。

🙏 致谢

内置：

Built because context matters, and Obsidian is where mine lives.

相关 MCP