Obsidian Notes

在 Claude Desktop 中安装

从最新版本下载适用于 Mac 或 PC 的安装包，打开后将其指向你的知识库。

关于“未签名”

这些安装包未经签名。对于 .mcpb 来说，这是正常的：mcpb pack 默认不会签名，而签名是一个单独的可选步骤，需要使用你自己的证书。如果你对下载的文件运行 mcpb info，会看到 WARNING: Not signed——请忽略它。这不会影响扩展的安装或使用。

目前尚未启用签名，因为上游工具存在问题：mcpb sign 生成的安装包会被 Claude Desktop 拒绝安装（#278），而 mcpb verify 会将已签名的安装包报告为未签名（#276）。这些问题修复后就会添加签名功能。

使用 Obsidian 的 MCP 工具

• 采用这样的思路：使用标签和搜索来查找本地信息，比使用 RAG 更好。
• Google 正在倡导的开放知识格式（OKF）有更多可能性。它主要使用 Markdown。
• Markdown、笔记以及更便捷的本地信息访问，让我觉得应该有一个能将大模型连接到 Obsidian 的应用。

目标

• 让工具通过标题、标签以及笔记中的链接来检查笔记
• 将知识库作为大模型记录笔记的空间，用于解决问题、记录文档，并判断新问题是否与已有问题相似

非目标

• 为应用创建完整的 GUI 界面
• 支持使用 RAG

安装

cargo install mcp-obsidian

然后将其指向一个知识库：

mcp-obsidian --vault ~/vault index      # print the index, no model involved
mcp-obsidian --vault ~/vault serve      # stdio MCP server for a desktop host
mcp-obsidian --vault ~/vault serve --http   # Streamable HTTP on 127.0.0.1:8000/mcp

市场目录

已发布到 crates.io： https://crates.io/crates/mcp-obsidian

cargo install mcp-obsidian
mcp-obsidian --vault ~/vault serve

该 crate 采用双许可证，其 README 中包含注册表所有权令牌，因此也可以在 Official MCP Registry 中列出，并作为 MCPB 安装包发布，无需进行其他更改。

• PUBLISHING.md — 发布操作手册，以及各个目录所需的账号。
• DEPLOYMENT.md — 在 VPS 上通过公开 HTTPS URL 托管，以及提交到 Smithery 和 ChatGPT 目录及其所需的 OAuth。

下面这一行是注册表用于验证此 crate 的 README 中所有权的令牌。它必须以纯文本形式保持可见——crates.io 会移除 HTML 注释——并且必须与 server.json 中的 name 相匹配。

mcp-name: io.github.moreno-omar/mcp-obsidian

演示

以下所有操作都在一台桌面电脑上本地运行——由 NVIDIA RTX 4060 Ti（16 GB）通过 Ollama 提供 gemma4:e4b 服务，并从磁盘读取知识库。无需 API 密钥，不调用云端服务，数据不会离开这台机器：唯一的网络流量是 localhost:11434。

ask — 提交一个提示词，从知识库中获得回答

chat — 相同的流程，支持交互

预览	展示内容
	index：每条笔记的链接数和标签，以表格形式呈现。
	chat：欢迎面板、工具调用记录，以及以 Markdown 渲染的回答。
	Phase 3 退出标准所依据的知识库内容：python/python_oneliners/list comprehensions.md。

快速，因为这是命令行工具，而不是完整的 TUI

mcp-obsidian 负责打印，而不负责绘制。它没有备用屏幕、没有事件循环，也没有逐帧重绘：颜色和布局由 richrs 针对每个回答计算一次，写入 stdout 后，进程就会退出。在上面那台机器上的测量结果：

步骤	测量结果
为包含 490 条笔记的库建立索引（启动时执行一次）	约 60 ms
查询库（search、index、MCP 工具调用）	约 60 ms，不涉及模型
完整的 ask 往返（预搜索 + 工具调用轮次 + 回答）	数秒——本地模型是唯一的耗时部分

完整的 TUI 每一帧都要执行一次布局并重绘终端，而流式聊天界面在此基础上还要为每个 token 额外执行一次。这里终端每个回答只写入一次，全部耗时都花在模型上，因此检索几乎瞬时完成，GPU 一处理完，回答就会立即输出。输出也保持为普通的 Unix 流：ask "…" > answer.md、| grep、NO_COLOR=1 和 FORCE_COLOR=1 都会按预期工作。

参考资料

• https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/

状态

阶段 1 已完成（2026-09-28）：命令行工具可以与 Ollama 通信，工具集通过 MCP 提供服务。

阶段 2 已完成（2026-10-01）：检索层和 Ollama 层拆分为小型模块（src/vault/、src/ollama_client/），并通过库目标提供，共有 32 个测试固定其行为。

阶段 3 已完成（2026-10-09）：ask 的回答以知识库为依据——采用命令式工具协议和确定性预搜索，因此即使模型从不调用工具，也能获取相关笔记。ask、chat、doctor、index、search 和 serve 的输出使用 richrs 和 Tokyo Night 主题渲染（通过管道输出时自动关闭颜色）。

阶段 4 正在进行（2026-10-09）：已作为 mcp-obsidian v0.1.0 发布到 crates.io（cargo install mcp-obsidian）。该二进制采用双重许可并附带注册表元数据；server.json 通过 Official MCP Registry 验证；scripts/build_mcpb.sh 会生成符合架构规范、可用于 Smithery 的 MCPB 包；serve --http 则为远程主机添加 Streamable-HTTP 传输。有关如何通过公开的 HTTPS URL 托管，以及如何将其列入 Smithery 和 ChatGPT 目录，请参阅 DEPLOYMENT.md；详情见 logs/2026-10-09_mcp_obsidian_phase4_publishing.md。

有关其工作原理及设计原因，请参阅 SUMMARY.md；有关如何阅读代码以及修改位置，请参阅 ARCHITECTURE.md；有关实现方式的比较，请参阅 logs/MCP_notes.md；有关已完成事项和后续计划，请参阅 TASKS.md。

用法

cargo build --release

# vault-only commands (no model needed)
./target/release/mcp-obsidian --vault ~/vault index
./target/release/mcp-obsidian --vault ~/vault search tag project --match-all
./target/release/mcp-obsidian --vault ~/vault search term "token budget"
./target/release/mcp-obsidian --vault ~/vault search links index --depth 2
./target/release/mcp-obsidian --vault ~/vault search note projects/alpha

# with Ollama (defaults: http://localhost:11434/v1, gemma4:e4b)
./target/release/mcp-obsidian --vault ~/vault doctor
./target/release/mcp-obsidian --vault ~/vault ask "what do my notes say about token budgets?" --trace
./target/release/mcp-obsidian --vault ~/vault ask "…" --no-prefetch   # no pre-search, tools only
./target/release/mcp-obsidian --vault ~/vault chat

# as an MCP server for a desktop host
./target/release/mcp-obsidian --vault ~/vault serve
./target/release/mcp-obsidian --vault ~/vault serve -vv   # log each tool call to stderr

# as an MCP server over Streamable HTTP (for a host that cannot spawn a process)
./target/release/mcp-obsidian --vault ~/vault serve --http            # 127.0.0.1:8000/mcp
./target/release/mcp-obsidian --vault ~/vault serve --http 0.0.0.0:8000
./target/release/mcp-obsidian --vault ~/vault serve --http 0.0.0.0:8000 \
  --allow-host vault.example.com                                      # accept that Host header

默认情况下，serve 使用 stdio，以便 stdout 保持为 JSON-RPC 通道；添加 --http 后，则会改为在 /mcp 上使用 Streamable HTTP。HTTP 模式没有身份验证——它默认绑定到回环地址，且 rmcp 会拒绝非回环地址的 Host 标头，因此在公开之前，请在它前面配置反向代理。有关 ChatGPT／插件目录的其他要求，请参阅 PUBLISHING.md。

可直接编辑的主机配置示例位于 claude_desktop_config.example.json。环境变量 OBSIDIAN_VAULT、OLLAMA_URL、OLLAMA_MODEL 和 RUST_LOG 可覆盖默认值；--api native 会将 /v1/chat/completions 切换为 /api/chat。只有输出到终端时才会显示颜色：NO_COLOR=1 可禁用颜色，FORCE_COLOR=1 可在通过管道输出时强制启用颜色。

回答会按终端宽度换行，续行与文本对齐，而不是与项目符号对齐。重定向的输出刻意不换行，因此 ask "…" > answer.md 会保留模型自身的行结构。

samples/vault/ 中提供了一个示例库，可用于尝试上述命令。

测试

cargo test                            # vault + ollama client; no model needed
cargo test -- --ignored live_client   # needs a running Ollama with the model pulled

许可证

您可以选择根据 Apache License, Version 2.0 或 MIT license 获得许可。

除非您明确声明另有规定，否则根据 Apache-2.0 许可证的定义，您有意提交以纳入此 crate 的任何贡献，均将按照上述方式以双重许可授权，且不附加任何条款或条件。