AI导哈

混合语义搜索服务器

obsidian-mcp是一个为Obsidian知识库设计的混合语义搜索服务器，结合BM25、Voyage AI嵌入和Cohere重排技术，提供高效的笔记检索和管理功能。

  • by tofunori
  • Python
  • 混合部署
  • 1 星标
  • 更新于
在 GitHub 查看 tofunori/obsidian-mcp

使用说明

黑曜岩mcp

用于黑曜石金库的MCP服务器，具有混合语义搜索功能。

特性

  • 混合搜索：BM25+Voyage AI嵌入+Cohere-reranking
  • 反向链接：预先计算的维基链接图
  • 类似注释：发现隐藏的连接
  • 完整CRUD：创建、读取、更新、删除、移动笔记
  • 实时索引：索引注释直接来自Claude Code，无需重新启动

安装

cd obsidian-mcp
uv sync

配置

  1. 复制 .env.example 到 .env 并添加您的API密钥：
VOYAGE_API_KEY=your_key
COHERE_API_KEY=your_key  # optional
  1. 在中设置vault路径 config/settings.yaml:
vault:
  path: "D:\\path\\to\\your\\vault"

用法

推荐工作流程（通过MCP）

建议的工作流程是直接使用Claude Code中的MCP工具：

1. write   -> Create or modify a note (auto-indexes by default)
2. search  -> Note is instantly searchable

注释在以下时间后自动索引 write，因此只需要手动索引：

  • 在Obsidian中手动创建的笔记（使用 index 工具）
  • 批量进口（使用 index 随着 full=True)

交互菜单

python obsidian-menu.py

命令行界面

# Full indexation
python obsidian-cli.py --vault "/path/to/vault" index --full

# Incremental indexation
python obsidian-cli.py --vault "/path/to/vault" index

# Status
python obsidian-cli.py --vault "/path/to/vault" status

# Search
python obsidian-cli.py --vault "/path/to/vault" search "query"

备注：由于ChromaDB缓存，CLI索引需要重新启动Claude Code才能在MCP搜索中看到更改。使用 index MCP工具用于实时更新。

Claude代码配置

选项1:HTTP/SSE服务器（推荐）

作为共享HTTP服务器运行，以避免在Claude会话之间重复进程。

1.启动HTTP服务器：

uv run python -m src.server_http
# Server runs on http://127.0.0.1:8322/mcp

2.配置克劳德代码 (~/.claude.json):

{
  "mcpServers": {
    "obsidian": {
      "type": "sse",
      "url": "http://127.0.0.1:8322/mcp"
    }
  }
}

3.（可选）作为systemd服务运行 （Linux）：

# Create ~/.config/systemd/user/obsidian-mcp.service
[Unit]
Description=Obsidian MCP HTTP Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/path/to/obsidian-mcp
Environment="VOYAGE_API_KEY=your_key"
Environment="COHERE_API_KEY=your_key"
Environment="OBSIDIAN_VAULT=/path/to/vault"
ExecStart=/path/to/uv run python -m src.server_http
Restart=on-failure

[Install]
WantedBy=default.target

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now obsidian-mcp

选项2：Stdio（每节课）

添加到 ~/.claude.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": ["--directory", "/path/to/obsidian-mcp", "run", "python", "-m", "src.server"],
      "env": {
        "VOYAGE_API_KEY": "your_key",
        "COHERE_API_KEY": "your_key",
        "OBSIDIAN_VAULT": "/path/to/vault"
      }
    }
  }
}

MCP工具

工具 说明
search 混合语义搜索（BM25+嵌入+重新排序）
read 阅读带有元数据和frontmatter的注释
write 创建或更新注释（默认情况下为自动索引）
delete 删除注释
move 移动或重命名注释
list 使用文件夹/标签过滤器列出笔记
backlinks 查找链接到笔记的笔记
similar 查找语义相似的注释
index 索引新的/修改的笔记（实时，无需重新启动）
refresh 从ChromaDB重建BM25索引
reload 重置所有缓存和连接

自动索引（写入工具）

默认情况下， write 在创建或修改注释后自动为其建立索引：

# Auto-indexes after writing (default)
write(path="Notes/my_note.md", content="...")

# Disable auto-indexing if needed
write(path="Notes/my_note.md", content="...", auto_index=False)

这使得新笔记无需手动索引即可立即搜索。

索引工具

这 index 工具直接在MCP服务器进程中索引注释，避免ChromaDB缓存同步问题：

# Incremental indexation (default)
index()  # Only indexes new/modified notes

# Full reindexation
index(full=True)  # Reindexes all notes

为什么使用 index 而不是CLI？

ChromaDB为每个进程维护一个HNSW索引缓存。当您通过CLI（单独的进程）进行索引时，MCP服务器在重新启动之前不会看到更改。这 index 该工具通过以下方式解决了这个问题：

  1. 在与MCP服务器相同的进程中运行索引
  2. 索引后重置内部缓存
  3. 使新笔记可立即搜索

项目结构

obsidian-mcp/
  src/
    server.py           # MCP server (11 tools)
    indexer.py          # Indexation engine
    retriever.py        # Hybrid search (BM25 + semantic + RRF)
    note_parser.py      # Obsidian markdown parser
    wikilink_graph.py   # Backlink graph
  config/
    settings.yaml       # Configuration
  chroma_db/            # Vector database (ChromaDB)
  obsidian-cli.py       # CLI interface
  obsidian-menu.py      # Interactive menu

技术细节

混合搜索管道

  1. BM25：精确术语匹配的词汇搜索
  2. 语义：Voyage AI嵌入(voyage-3)为了意义
  3. 融合：互惠排名融合（RRF）结合了结果
  4. 重新排序：Cohere-reranker(rerank-v4.0-pro)用于最终订购

嵌入模型

  • 型号： voyage-3
  • 尺寸：1024
  • 提供商：Voyage AI

数据库

  • 具有持久存储的ChromaDB
  • 具有WAL模式的SQLite后端
  • 用于快速相似性搜索的HNSW索引

许可证

麻省理工学院

相关 MCP