AI导哈

Obsidian MCP服务器

一个MCP（模型上下文协议）服务器，允许AI代理在Obsidian库中工作，包括读取笔记、搜索上下文、检查链接等功能，并可安全地创建或编辑笔记。

  • by Vasallo94
  • Python
  • 本地部署
  • 11 星标
  • 更新于
在 GitHub 查看 Vasallo94/obsidian-mcp-server

使用说明

黑曜石MCP服务器


一 MCP（模型上下文协议） 该服务器允许AI代理在黑曜石金库内工作：读取笔记、搜索上下文、检查链接、遵循金库特定规则，并可选择安全地创建或编辑笔记。

它专为客户和线束而设计，例如 法典, 克劳德代码, 赫尔墨斯，以及 克劳德桌面版核心保持可重复使用；每个vault都可以将自己的配置文件、规则、技能和可选工具集分层。

工具是通用的。行为源于保险库。

flowchart LR
    Clients["Codex, Claude Code, Hermes, Claude Desktop"] --> MCP["Obsidian MCP Server"]
    MCP --> Core["Core tools: read, search, inspect, route"]
    MCP --> Optional["Optional tool sets: write, graph, canvas, ObsidianRAG"]
    Core --> Vault["Obsidian vault"]
    Optional --> Vault
    Vault --> Profile[".agents/vault.yaml, rules, skills, standards"]
    Profile --> MCP

特征

公共核心

核心工具集始终可用，并且与保险库无关：

  • 保险库诊断、任务路由和MCP客户端根检查。
  • 注释列表、读取、元数据检查和搜索。
  • 用于配置文件、技能、标准和本地文档的Vault上下文资源。
  • 结构化笔记、模板使用和上下文探索的核心提示。

可选工具集

从中显式启用可选包 .agents/vault.yaml 或 OBSIDIAN_MCP_TOOL_SETS:

  • notes_write：创建、修补、移动和删除笔记。
  • vault_analysis：Vault统计信息、标记、链接、反向链接和图形工具。
  • agents_admin：技能创建、验证和缓存管理。
  • youtube：转录摘录。
  • obsidianrag：通过外部ObsidianRAG服务进行语义搜索。
  • canvas / kanvas：画布和工作流助手。
  • 配置文件包：仅当选择vault配置文件时，才执行个人工作流。

设计原则

  • 公共核心、个人资料存储库仍可重复使用；本地工作流存在于vault配置和资源中。
  • 英语技术面：工具名称、提示名称、文档和代码标识符均为英文。
  • 默认安全：写入工具是选择加入的，受保护的路径被阻止，大型读取被限制。
  • 通过整合实现外部RAG：高级语义搜索委托给ObsidianRAG，而不是在MCP服务器内复制RAG堆栈。

快速开始

先决条件

  • 紫外线
  • 您可以放心地将黑曜石保险库路径暴露给MCP客户端

从Git进行Beta版安装

在包发布到PyPI之前，直接从GitHub安装 uvx:

uvx --from git+https://github.com/Vasallo94/obsidian-mcp-server.git obsidian-mcp-server

对于Codex，请将此添加到 ~/.codex/config.toml:

[mcp_servers.obsidian]
command = "uvx"
args = [
  "--from",
  "git+https://github.com/Vasallo94/obsidian-mcp-server.git",
  "obsidian-mcp-server",
]
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.obsidian.env]
OBSIDIAN_VAULT_PATH = "/absolute/path/to/your/vault"

有关Claude Code、Hermes、Claude Desktop和MCPB设置，请参阅 安装.

本地开发

git clone https://github.com/Vasallo94/obsidian-mcp-server.git
cd obsidian-mcp-server
make install
cp .env.example .env
# Set OBSIDIAN_VAULT_PATH to the absolute path to your Obsidian vault
uv run obsidian-mcp-server

一旦包发布到PyPI，客户端配置就可以使用：

uvx obsidian-mcp-server

用法

可选工具集

从客户端环境启用可选工具：

{
  "env": {
    "OBSIDIAN_VAULT_PATH": "/Absolute/Path/To/Your/Vault",
    "OBSIDIAN_MCP_TOOL_SETS": "notes_write,vault_analysis,obsidianrag"
  }
}

或者在您的vault配置文件中声明它们：

profile:
  name: "my_profile"
  prompt_sets:
    - "mermaid"
  tool_sets:
    - "notes_write"
    - "vault_analysis"
  standards:
    media: "Standards/Media.md"
  local_docs:
    index: "README.md"

黑曜石RAG集成

对于语义库搜索，启用 obsidianrag 工具集并声明 集成：

profile:
  tool_sets:
    - "obsidianrag"
  integrations:
    obsidianrag:
      project_path: "/path/to/ObsidianRAG"
      api_url: "http://127.0.0.1:8000"
      env:
        OBSIDIANRAG_LLM_MODEL: "gemma3"
        OBSIDIANRAG_OLLAMA_EMBEDDING_MODEL: "embeddinggemma"

然后阅读 obsidian://integrations/obsidianrag/setup 或致电 rag.setup_status。代理应在安装前显示安装命令 依赖关系、启动服务、拉取模型或重建索引。

技术文档

要更深入地了解服务器的工作原理以及如何对其进行自定义，请查看我们位于 docs/ 文件夹：

  1. 文档主页：项目文档的Wiki样式地图。
  2. 安装：Codex、Claude Code、Hermes、Claude Desktop和MCPB的设置。
  3. 建筑：运行时架构、工具集、资源、提示和安全模型。
  4. 工具参考：公共MCP工具的完整列表。
  5. 服务器配置：环境变量、vault配置文件、工具集和集成。
  6. 代理设置：如何组织您的保险库(.agents/)有技能和上下文规则。
  7. 语义搜索：黑曜石RAG集成和遗留RAG迁移说明。
  8. 代理商反馈：代理人如何报告MCP与AFP的摩擦。
  9. 未来路线图：服务器的计划改进和下一步行动。

有关贡献、发布和安全过程，请参阅 贡献.md, 安全.md，以及 发布检查表.

发展与质量

命令 描述
make test 运行测试套件（pytest）
make lint 运行静态检查（Ruff+Pyright）
make format 自动格式化代码
make dev 在本地运行MCP服务器

许可证

该项目根据MIT许可证获得许可。

相关 MCP