obsidian-mcp-secure

obsidian-mcp-secure

安全的 Model Context Protocol 服务，可将你的 Obsidian 知识库转化为可靠的数据源，供任何兼容 MCP 的 AI 客户端使用——从零构建，包含 OWASP Top 10 防护措施和完整的审计日志。

已列入 Anthropic 官方 MCP Registry，名称为 io.github.dewtech-technologies/obsidian-mcp-secure。

---

🧭 定位——这不是 Obsidian 插件

恰恰相反：它是一个桥接工具，可让 Claude Desktop（或任何 MCP 客户端）安全地读取和写入 Obsidian 中的内容。你的 AI 助手仍在原来的位置；你的知识库则成为它可访问的结构化、可审计数据源。

┌─────────────────┐   MCP    ┌──────────────────────┐   HTTP   ┌────────────────────┐   FS   ┌─────────────┐
│                 │  stdio   │                      │  :27123  │                    │        │             │
│ Claude Desktop  │ ───────▶ │ obsidian-mcp-secure  │ ───────▶ │  Local REST API    │ ─────▶ │  Vault .md  │
│  (AI client)    │          │  (this package)      │          │ (Obsidian plugin)  │        │             │
└─────────────────┘          └──────────────────────┘          └────────────────────┘        └─────────────┘

工作流中的角色	组件
你交谈的地方	Claude Desktop（或任何 MCP 客户端）
桥接／访问控制	obsidian-mcp-secure（此软件包）
Obsidian 内部的数据网关	Local REST API 插件（由 Adam Coddington 开发）
你的知识	知识库中的 .md 文件

一句话概括： Claude 是大脑，这个 MCP 是手臂，Obsidian 是记忆。

为什么还需要另一种 Obsidian + AI 集成？

有些插件会把 Claude 放进 Obsidian。这个工具恰好相反，推出它的原因是：

• 你的助手是 Claude Desktop——通用对话都在这里进行。你的笔记会成为 Claude 可访问的众多上下文之一，与网页、GitHub、文件系统等并列。
• 安全是首要考虑——有意控制攻击面，不提供 shell 访问，阻止路径遍历，使用 Zod 验证输入，并审计每次调用。
• 无需构建，无需账户——运行 npx obsidian-mcp-secure 即可。它在 Windows、macOS 和 Linux 上的使用方式相同。
• 可组合性——将此 MCP 与 fetch、文件系统、git、GitHub 等结合，Claude 就能在一次对话中交叉参考你的知识库和外部来源。

---

🛠️ 可用工具

工具	用途
read_note	按路径读取笔记
list_notes	列出知识库或子目录中的文件／文件夹
create_note	创建新的 .md 笔记
edit_note	覆盖现有笔记（之前的内容会写入审计日志）
delete_note	删除笔记——需要 confirm: true（否则 Zod 会拒绝）
search_notes	使用 Obsidian 自带的搜索引擎进行全文／标签搜索
find_note_by_name	按部分名称查找笔记——不区分大小写，无需提供完整路径
list_tags	列出知识库中的所有标签及其使用次数；可按名称或频率排序
create_backlinks	在笔记的 ## Relacionadas 区块中添加 [[wikilinks]]——明确且可审计

---

🔒 安全 — OWASP Top 10

控制项	实现方式
A01 — 访问控制失效	阻止路径遍历（../、..\\、编码变体）；强制使用 .md 扩展名
A02 — 加密机制失效	从 .env 或进程环境中读取 API 密钥；绝不硬编码，也绝不记录到日志
A03 — 注入	使用 Zod 模式验证所有输入；不使用 eval、exec 或 shell
A04 — 不安全设计	笔记大小上限为 512 KB；搜索结果上限为 50 条；破坏性操作必须显式设置 confirm: true
A05 — 安全配置错误	仅接受 127.0.0.1 / localhost 作为主机
A09 — 日志记录与监控	通过 winston 记录完整审计日志，并按大小轮转（5 MB / 10 个文件）

每次工具调用都会生成一条审计记录，包含 action、params（已清理）、success、error 和 timestamp。

---

⚡ 安装

前置条件

1. 已打开一个库的 Obsidian 桌面版
2. Local REST API 插件（由 Adam Coddington 开发）——从社区插件中安装并启用，然后：
   • 开启 “Enable Non-encrypted (HTTP) Server”（比 HTTPS 自签名证书更简单）
   • 复制插件设置中显示的 API Key
3. Node.js 18+
4. Claude Desktop（或其他兼容 MCP 的客户端）

配置 Claude Desktop

在 Windows 上打开 %APPDATA%\Claude\claude_desktop_config.json（或在 macOS 上打开 ~/Library/Application Support/Claude/claude_desktop_config.json），并添加：

{
  "mcpServers": {
    "obsidian-secure": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-secure"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-from-the-plugin",
        "OBSIDIAN_HOST": "http://127.0.0.1",
        "OBSIDIAN_PORT": "27123",
        "LOG_DIR": "C:/path/to/your/logs"
      }
    }
  }
}

**Windows 提示：**如果 npx 静默失败，请将 "command": "npx" 改为 "command": "npx.cmd"。某些 Claude Desktop 版本无法从 PATH 中解析裸的 npx。

重启 Claude Desktop（系统托盘 → 退出，然后重新打开），9 个工具便会显示在 obsidian-secure 下。

---

🤝 推荐搭配

MCP 的真正优势在于组合能力。要实现 “读取我的笔记 → 获取一个 URL → 告诉我是否正确应用了其中的内容” 这一工作流，请将官方的 fetch MCP 与此 MCP 一起添加：

{
  "mcpServers": {
    "obsidian-secure": { "...": "as above" },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

现在，Claude 可以在同一段对话中访问你的知识库和实时网络。

---

💬 示例提示词

启用 obsidian-secure + fetch 后：

“读取我的笔记 Projeto API Atendimento.md，然后获取 https://developers.facebook.com/docs/whatsapp，并告诉我我的实现是否符合最新的最佳实践。”

“搜索我的知识库，查找标签 #ideia，并总结最常出现的三个想法。然后创建一篇名为 Ideias recorrentes.md 的新笔记，并写入总结。”

“读取 Atomic Habits - Resumo.md，获取 https://jamesclear.com/atomic-habits，并指出我的笔记与原文有哪些出入。”

Claude 会自动协调工具调用，无需手动串联。

---

🧩 与 Obsidian 内插件的比较

如果你的工作流位于 Obsidian 侧边栏中，那么 obsidian-claude-code 之类的插件更适合你。此 MCP 面向不同的使用场景：

维度	obsidian-claude-code（Obsidian 内）	obsidian-mcp-secure（此项目）
AI 所在位置	Obsidian 内的侧边栏	Claude Desktop（或任何 MCP 客户端）
设置	git clone + bun build	npx obsidian-mcp-secure
工具	读取/写入/编辑 + Bash + Grep + Glob + WebFetch	9 个专用且经 Zod 验证的工具
安全状况	可完全访问开发机器上的 shell	严格的允许列表、经过审计，符合 OWASP Top 10
分发方式	手动克隆，需要 Bun	npm + 官方 MCP Registry
与其他来源的组合能力	在自身沙箱内	任何兼容 MCP 的客户端都可将其与 fetch、GitHub、filesystem 等组合使用
最适合	日常使用 Obsidian 的开发者	主要使用 Claude Desktop 的专业人士

两者都各有价值，适用于不同的场景。

---

🔧 环境变量

变量	必需	默认值	描述
OBSIDIAN_API_KEY	✅	—	Local REST API 插件提供的 API 密钥
OBSIDIAN_HOST		http://127.0.0.1	主机（仅接受 127.0.0.1 和 localhost）
OBSIDIAN_PORT		27123	插件 HTTP 服务的端口
LOG_DIR		./logs	审计日志文件的目录

---

🗺️ 路线图

✅ 已在 v1.2.1 中发布

• 修复错误：find_note_by_name 会搜索完整路径（文件夹 + 文件名）
• 修复错误：list_tags 会规范化所有 API 响应格式（对象、字符串数组、包含 tagCount/taggedFilesCount 的对象数组）

✅ 已在 v1.2.0 中发布

• DXT 包，可在 Claude Desktop 中一键安装（npm run build:dxt）

✅ 已在 v1.1.0 中发布

• find_note_by_name — 在整个库中按名称进行部分匹配，不区分大小写
• create_backlinks — 使用 [[wikilinks]] 连接相关笔记（明确、可审计）
• list_tags — 列出库中的所有标签及其使用次数
• 使用 Vitest 编写的单元测试套件（70 项测试 — utils、handlers、HTTP client）
• 每次 PR 都会运行 CI 流水线：测试 + 覆盖率 + npm audit + 静态安全分析

🔜 后续计划

• 在 Smithery 上架
• 为共享 / 多用户设置提供只读模式标志

欢迎提交创意和 PR — 请参阅 CONTRIBUTING.md。

---

📜 许可证

MIT — 请参阅 LICENSE。

🙏 致谢

• Anthropic 提供的 Model Context Protocol
• Adam Coddington 提供的 Local REST API 插件 — 这是实现本项目的基础
• 由 Wanderson Leandro 在 Dewtech 构建

---

安全问题？ 请参阅 SECURITY.md 了解披露说明。