obsidian-mcp-server

一个用于 Obsidian 学习库的 MCP 服务器（模型上下文协议）。 让 Claude 能够访问笔记搜索、笔记内容、以卡片组格式创建闪卡， 以及学习追踪插件的学习计划。

Python，MCP SDK 2.x，stdio 传输。

用途

此前，逻辑分散在两个 Obsidian 插件中：

• Decks（第三方插件）负责渲染闪卡，但不会创建闪卡——卡片 都是手工编写的。

• Lerntracker（自有插件）管理学习进度和学习计划， 但不会自动将内容分配到具体日期。

这个服务器弥补了两个缺口：Claude 可以直接以现有 文件格式创建卡片，并计算学习计划，写回 Lerntracker 的 data.json。

Related MCP server: Nexus MCP for Obsidian

安装

cd ~/Projects/obsidian-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

配置

两个路径都来自环境变量——没有硬编码。

Vault 路径的默认值适用于 iCloud 同步的 Obsidian； 对于其他设置，只需设置 OBSIDIAN_VAULT_PATH。

Lerntracker 路径可以单独设置，因为 Obsidian 库可能嵌套： 如果子文件夹中还有另一个库，它会有自己的 data.json。默认值指向主库的路径。

工具

所有模式均由 SDK 根据类型提示和文档字符串自动生成——代码中 没有手写的 JSON 模式。

闪卡格式

create_flashcard 精确写入库中现有卡片使用的格式 （标题 + 段落），并附加指向来源笔记的维基链接：

---
tags: [decks]
---

## Was ist ein Signal?

Eine zeitabhängige, messbare physikalische Größe.

Quelle: [[01_Physikalische_Schicht]]

目标文件路径由来源笔记的课程文件夹决定；deck 会覆盖 文件名。如果文件不存在，会以 tags: [decks] 创建。 如果存在完全相同的问题，则跳过而不是 重复创建。

牌组的学习状态存储在 SQLite 数据库中，而不是 Markdown 文件中。服务器不会修改它——FSRS 历史记录 保持不变。

为什么 generate_summary 不自己生成摘要

服务器没有语言模型。它只返回结构化笔记 （大纲、关键数字、全文）；摘要由客户端侧的模型生成—— 也就是 Claude Desktop。随后通过 save_summary 保存。这是常见的 MCP 角色分工：服务器提供 上下文并执行操作，模型负责撰写。

如果服务器自己生成摘要，就需要调用 Anthropic API 并持有自己的 API 密钥。

学习计划逻辑

generate_study_plan 将每个未学习的子主题分配到具体日期：

1. 课程按考试日期排序——最早的考试优先。

2. 学习截止日期 = examDate − bufferDays；缓冲天数保留用于复习。

3. 学习日来自 settings.weeklyHours（0 = 周日 … 6 = 周六）。值为 0 的天以及所有 blockedDates 会被跳过。

4. 每个子主题需要 hours_per_subtopic（默认 1.5 小时），并分配到 剩余容量最早的一天。如果一天放不下， 则拆分到多天——插件支持多个 dates。

5. 已完成的子主题以及已有 dates 的子主题保持不变。

6. 无法在截止日期前安排的内容会作为警告报告，而不是静默丢弃。

每次写入前，会在文件旁创建备份 （data.backup-<时间戳>.json）；写入通过临时文件原子完成。 dry_run=True 仅显示计划。

写入后，在 Obsidian 中按 Cmd+R 刷新，让插件重新加载。

资源

模板特意使用 {+path}（保留展开）而不是 {path}。 普通模板变量不匹配斜杠——使用 {path} 会导致子文件夹中的 笔记被静默地找不到，而库中 几乎每个笔记都在课程文件夹里。

使用 MCP Inspector 本地测试

Inspector 通过 SDK 的 CLI 启动，并打开一个 Web 界面， 可以在其中单独调用工具和资源。需要 npx （Node.js）和 uv。

source .venv/bin/activate && mcp dev main.py

该命令会输出一个类似 http://localhost:6274 的 URL（带有附加的 会话令牌）。在浏览器中打开，点击左侧的 Connect，然后：

• Tools 选项卡 → List Tools → 选择一个工具，填写参数，Run Tool

• Resources 选项卡 → List Resources → 点击 vault://structure

• 对于模板化资源，直接输入 URI，格式为 note://<课程文件夹>/Flashcards/<文件>.md

使用不同的库：

OBSIDIAN_VAULT_PATH="$HOME/Pfad/zu/deinem/Vault" mcp dev main.py

尝试写入工具时，建议使用一个一次性库：

OBSIDIAN_VAULT_PATH=/tmp/testvault mcp dev main.py

连接 Claude Desktop

配置文件： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "/Users/DEIN_NAME/Projects/obsidian-mcp-server/.venv/bin/python",
      "args": ["/Users/DEIN_NAME/Projects/obsidian-mcp-server/main.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/DEIN_NAME/Pfad/zu/deinem/Vault"
      }
    }
  }
}

重要：使用绝对路径——这里不会展开 ~ 和 $HOME。 command 要指定 venv 中的 Python：Claude Desktop 启动服务器时不会激活环境，仅使用 "python3" 会找不到 mcp 包。

如果文件已存在，只需将 "obsidian-vault" 条目插入现有的 mcpServers 对象中。之后完全退出并重新启动 Claude Desktop；服务器会出现在输入框的工具菜单中。

安全性

来自工具或资源调用的每个路径都会对照库进行检查： 拒绝绝对路径和 .. 穿越，且解析后的目标必须 位于 OBSIDIAN_VAULT_PATH 之内。.obsidian、.git、.trash、 .claude 和 node_modules 被排除在搜索和结构列出之外—— 否则插件包会淹没结果。

save_summary 不会覆盖已有文件，create_flashcard 不会 创建重复卡片，generate_study_plan 在写入前会备份 data.json。

测试情况

针对 Python 3.14 上的 mcp 2.0.0 进行了测试：工具模式、资源模板、 与真实 ClientSession 的 stdio 握手、路径防护，以及 针对一次性库的写入工具测试（包括多天拆分、 被阻止的日期、零小时的工作日以及溢出情况）。

许可证

MIT——参见 LICENSE。