Smart Connections MCP Server

让 Claude 真正拥有对 Obsidian 库的语义记忆。 这是一个 MCP 服务器，通过含义搜索你的笔记——复用 Smart Connections Obsidian 插件已生成的嵌入，并在本地运行相同的嵌入模型来理解你的查询。无需云端调用；你的库永远不会离开你的机器。

功能

• search_notes — 跨一个或多个库进行语义搜索。匹配整篇笔记以及单个章节（块），返回按相似度排序的结果及内容片段。

• get_similar_notes — 与给定笔记相似的笔记（已存储的嵌入）。

• get_connection_graph — 向外遍历相似度链接，绘制相关想法图谱。

• get_note_content — 读取笔记，或提取特定块。

• list_vaults / get_stats — 已加载内容、数量、模型、加载错误。

Related MCP server: ob-smart-connections-mcp

环境要求

• Node.js 20+

• 一个安装了 Smart Connections 插件并已生成嵌入的 Obsidian 库（v2 已针对 Smart Connections 3.x 数据测试）

• 一个 MCP 客户端（Claude Desktop、Claude Code 等）

设置（Claude Desktop）

添加到 claude_desktop_config.json 并重启 Claude Desktop：

{
  "mcpServers": {
    "smart-connections": {
      "command": "npx",
      "args": ["-y", "smart-connections-mcp"],
      "env": {
        "SMART_VAULT_PATH": "/path/to/Vault One,/path/to/Vault Two"
      }
    }
  }
}

一个库或多个库——用逗号分隔路径。

SMART_VAULT_PATHS（复数形式）也可作为 SMART_VAULT_PATH 的别名，若两者同时设置，则优先使用前者。

Claude Code

claude mcp add smart-connections -e SMART_VAULT_PATH="/path/to/vault" -- npx -y smart-connections-mcp

工作原理

Smart Connections 将每篇笔记和每个块的嵌入向量存储在 .smart-env/ 中。此服务器将这些向量加载到内存中，当你搜索时，使用你的库所用的相同模型嵌入你的查询（下载一次，约 25MB，通过 transformers.js 在本地运行）。结果按余弦相似度排序。你在 Obsidian 中所做的编辑会被自动捕获。

如果嵌入模型无法加载（例如首次运行时无网络），或某个库尚无嵌入，搜索将降级为字面关键词匹配，并明确说明（"mode": "keyword-fallback" 以及一个指明原因的 warning）。当只有部分库降级时，mode 保持 "semantic"，这些行带有 "match": "keyword"，并且始终排在真正的语义行之后。

从 v1 迁移

• 已移除 get_embedding_neighbors。

• search_notes 现在是真正的语义搜索，其响应包含 vault、scope、block、snippet 和 mode 字段。

• 其余内容均向后兼容；单库 SMART_VAULT_PATH 配置可原样使用。

开发

npm install
npm test              # build + CI-tier tests (no network)
npm run test:live     # + real-model tests (downloads ~25MB once)
npm run smoke -- "/path/to/vault" "your query"

MIT — 参见 LICENSE。