/ 目录 / 演练场 / Obsidian MCP Tools
● 社区 jacksteamdev ⚡ 即开即用

Obsidian MCP Tools

作者 jacksteamdev · jacksteamdev/obsidian-mcp-tools

为你的 Obsidian 知识库添加真正的 MCP 接口——通过 Smart Connections 实现语义搜索、Templater prompt 执行、完整文件 CRUD——无需离开编辑器。

Obsidian MCP Tools 以社区插件和 MCP 桥接的形式发布,让 Claude 能语义搜索你的知识库(通过 Smart Connections)、以 prompt 方式执行 Templater 模板、创建/读取/更新笔记。本地优先——不会将你的笔记上传到任何 SaaS——并与你可能已在使用的 Obsidian 社区插件生态深度集成。

为什么要用

核心特性

实时演示

实际使用效果

obsidian-mcp-tools.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "obsidian-mcp-tools": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-tools"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "obsidian-mcp-tools": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-tools"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "obsidian-mcp-tools": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-tools"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "obsidian-mcp-tools": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-tools"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "obsidian-mcp-tools",
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp-tools"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "obsidian-mcp-tools": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "obsidian-mcp-tools"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add obsidian-mcp-tools -- npx -y obsidian-mcp-tools

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Obsidian MCP Tools

如何真正查询你的第二大脑,而不是用关键词硬搜

👤 拥有 1000+ 笔记的 Obsidian PKM 用户 ⏱ ~20 min intermediate

何时使用: 你知道几个月前写过某些内容,但关键词搜索总是找不到。

前置条件
  • Obsidian + 本插件 + Smart Connections 插件 — 从社区插件中安装两者;Smart Connections 首次运行时会建立索引
步骤
  1. 检查索引
    Verify Smart Connections has finished embedding my vault. Report total notes indexed.✓ 已复制
    → 已索引笔记数量;正在使用的嵌入模型
  2. 语义召回
    Find notes related to 'why I left my last job' even if those exact words aren't in any note.✓ 已复制
    → 5 条按语义相关性排序的笔记,附摘要
  3. 整合
    Synthesize those into a short reflection note. Save under /Reflections/ with a wikilink to each source.✓ 已复制
    → 新笔记已创建;反向链接正常解析

结果: 一个能用概念而非关键词回答的第二大脑。

注意事项
  • 语义召回会浮现敏感的个人笔记 — 在 Smart Connections 中使用 Obsidian 的 excludedFolders 设置,跳过私密目录
搭配使用: humanizer-skill

从 Claude 运行 Templater 模板,自动填写 prompt

👤 拥有自定义模板的 Obsidian 高级用户 ⏱ ~10 min intermediate

何时使用: 你有一个「项目启动」Templater 模板需要填写 5 个 prompt;宁愿让 Claude 来编排。

前置条件
  • 已安装 Templater 并配置好模板 — 标准社区插件安装
步骤
  1. 列出模板
    What Templater templates are available?✓ 已复制
    → 模板列表,含 prompt 描述
  2. 自动填写运行
    Run 'project_kickoff' for a project called 'Q3 onboarding overhaul'. Auto-answer the prompts based on context.✓ 已复制
    → 使用模板创建新笔记;prompt 已填写

结果: 通过聊天而非弹窗方式运行模板。

注意事项
  • 部分 Templater 命令是异步的,需要时间 — MCP 工具会等待完成——但不要在一次调用中链式执行太多

从昨天的日历和任务自动构建每日笔记

👤 注重生产力的 Obsidian 用户 ⏱ ~15 min intermediate

何时使用: 每天开始都要编辑同一个「每日」模板——自动化它。

步骤
  1. 拉取今日数据
    Read yesterday's daily note. Carry forward incomplete tasks. Pull today's calendar via google-calendar MCP.✓ 已复制
    → 已识别待转移任务 + 今日事件
  2. 写入每日笔记
    Create today's daily note in /Daily/$(date +%F).md with the standard sections.✓ 已复制
    → 笔记已创建并打开

结果: 5 秒内完成每日笔记。

注意事项
  • 如果同一任务出现在两天的笔记中,转移时会重复 — 写入前按行文本去重
搭配使用: google-calendar

组合

与其他 MCP 搭配,撬动十倍杠杆

obsidian-mcp-tools + google-calendar

构建包含当天日程的每日笔记

Make today's daily note. Include calendar events under '## Today'.✓ 已复制
obsidian-mcp-tools + github

将项目看板同步到知识库笔记

Sync GitHub project XYZ tasks to /Projects/XYZ.md as a checklist.✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
search_semantic query, k? 概念层面的内容召回 1 次 Smart Connections 查询
read_note path 拉取单条笔记 免费
write_note path, content, mode: 'create'|'append'|'overwrite' 创建或更新笔记 免费
list_templates (无) 发现可执行的模板 免费
run_templater template_name, prompt_answers: {} 执行模板化工作流 免费

成本与限制

运行它的成本

API 配额
本地运行——如果 Smart Connections 使用云端服务则受其限制
每次调用 Token 数
每条笔记 100–1500 token
费用
免费(插件本体);Smart Connections 提供免费本地模式和付费云端选项
提示
在 Smart Connections 中使用本地嵌入选项,避免按查询计费

安全

权限、密钥、影响范围

凭据存储: 仅本地插件;无远程存储
数据出站: 本地——除非 Smart Connections 配置为使用云端嵌入

故障排查

常见错误与修复

MCP 工具未显示

确认 Obsidian 插件已启用,且 MCP 桥接进程正在运行

验证: 检查插件状态栏;重启 Obsidian
search_semantic 返回空结果

Smart Connections 的嵌入任务可能尚未完成——检查进度

验证: 打开 Smart Connections 侧边栏
write_note 因「路径超出知识库范围」而失败

路径相对于知识库根目录;不要使用绝对路径

替代方案

Obsidian MCP Tools 对比其他方案

替代方案何时用它替代权衡
ergut/mcp-logseq你使用的是 Logseq 而非 Obsidian不同的生态,相同的思路
AgriciDaniel/claude-obsidian(skill)你需要构建在文件 IO 之上的 skill 风格工作流skill 层次更高;此 MCP 是基础构建块

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills