使用说明

黑曜石MCP服务器

用于管理黑曜石保险库中技术笔记和文档的模型上下文协议（MCP）服务器。使用 官方黑曜石CLI （随Obsidian 1.12+附带）通过Obsidian的运行时与您的保管库进行交互，确保正确的链接更新、插件感知和索引一致性。

特性

核心笔记管理

编写/更新笔记 -用元数据创建或覆盖笔记
附加内容 -向现有笔记添加内容（可选部分定位）
章节更新 -按标题更新特定章节
阅读笔记 -检索笔记内容
列表注释 -使用目录和模式过滤浏览笔记
搜索 -在所有笔记中使用上下文进行全文搜索
删除笔记 -删除笔记（移至黑曜石垃圾箱）

组织工具

创建索引 -使用维基链接构建有组织的导航页面
添加反向链接 -将相关笔记链接在一起
保存对话 -自动标记时间戳并对讨论进行分类
模板 -从预定义模板创建注释

运作原理

所有操作都经过 obsidian CLI二进制文件，与正在运行的Obsidian实例通信。这意味着：

黑曜石的内部索引保持最新
维基链接得到妥善维护
插件会立即看到更改
对vault文件没有直接的文件系统操作

先决条件

黑曜石1.12+ 已注册CLI（设置>常规>命令行界面>注册CLI）
Python 3.8+
克劳德代码

验证CLI是否正常工作：

obsidian vaults verbose
# Should show your vault name and path

安装

克隆此存储库：

git clone https://github.com/erictt/obsidian-notes-mcp.git
cd obsidian-notes-mcp

运行安装脚本：

./install.sh

通过添加到以下代码注册Claude Code ~/.claude/.mcp.json:

{
  "mcpServers": {
    "obsidian-notes": {
      "type": "stdio",
      "command": "/path/to/obsidian-notes-mcp/venv/bin/python",
      "args": ["/path/to/obsidian-notes-mcp/server.py"],
      "env": {
        "OBSIDIAN_VAULT_NAME": "YourVaultName"
      }
    }
  }
}

重新启动Claude代码

配置

环境变量

变量	默认值	描述
`OBSIDIAN_VAULT_NAME`	`Shopify`	黑曜石拱顶的名称（如图所示 `obsidian vaults`)
`OBSIDIAN_CLI_PATH`	`obsidian`	Obsidian CLI二进制文件的路径
`OBSIDIAN_CLI_TIMEOUT`	`30`	CLI命令超时（秒）（可能需要启动Obsidian）

目录结构

按类别组织您的保险库：

Vault/
├── App Infra/          # Infrastructure docs
├── Tech/               # Technical notes
├── Team/               # Team docs
└── ...

用法

自然语言

只需与克劳德自然地谈论你的笔记：

"Save this conversation about Kubernetes networking"
"Add this to the runtime-engine note under Key Learnings"
"Create an index for all App Infra notes"
"Search my notes for cluster commissioning"

可用工具

write_note

用元数据创建或覆盖注释。

{
  "path": "App Infra/New Note.md",
  "content": "# Title\n\nContent here",
  "tags": ["kubernetes", "infrastructure"],
  "metadata": {"author": "eric"}
}

附录_注释

将内容附加到现有注释中，可以选择在特定部分下。

{
  "path": "Tech/kubernetes.md",
  "content": "New information here",
  "section": "Key Learnings"
}

update_note_section

更新或创建特定部分。

{
  "path": "App Infra/Clusters.md",
  "section": "## Overview",
  "content": "Updated overview content"
}

read_note

阅读笔记内容。

{
  "path": "Tech/kubernetes.md"
}

list_notes

列出所有带有可选过滤功能的笔记。

{
  "directory": "App Infra",
  "pattern": "cluster"
}

search_notes

在所有带有上下文的笔记中搜索。

{
  "query": "kubernetes networking",
  "directory": "Tech"
}

create_index

创建一个有组织的索引页面。

{
  "index_path": "App Infra/Index.md",
  "title": "Infrastructure Documentation",
  "sections": {
    "Clusters": ["Cluster Management.md", "Commissioning.md"],
    "Deployment": ["Application Deployment.md", "Tooling.md"]
  }
}

add_backlinks

添加相关注释部分。

{
  "path": "App Infra/Clusters.md",
  "related_notes": ["Application Deployment", "Tooling"]
}

create_conversation_note

使用自动时间戳保存对话。

{
  "topic": "Target Filename Patterns",
  "content": "Discussion about...",
  "category": "App Infra",
  "tags": ["infrastructure", "kubernetes"],
  "related_notes": ["Cluster Management"]
}

delete_note

删除笔记（移至黑曜石垃圾箱）。

{
  "path": "App Infra/Old Note.md"
}

模板

服务器包括6个标准化模板，用于一致的笔记记录：

对话 -技术讨论和问答
如何 -分步指南
概念 -系统解释和架构
故障排除 -事件报告和调试
参考 -命令备忘单和配置
决定 -架构决策记录

看模板.md 了解详细的模式和使用指南。

从模板创建笔记

{
  "template": "how-to",
  "path": "Tech/Deploy to Production.md",
  "variables": {
    "topic": "Deploy to Production",
    "goal": "Deploy application safely to production",
    "related_notes": ["CI/CD", "Kubernetes"]
  }
}

元数据

注释包括YAML frontmatter：

---
created: 2026-02-11
last_modified: 2026-02-11 11:43
type: conversation
topic: Kubernetes Networking
tags:
  - kubernetes
  - networking
---

故障排除

未找到CLI

确保安装了黑曜石1.12+
注册CLI：设置>常规>命令行界面>注册CLI
验证： which obsidian 应该返回一条路径

命令超时

黑曜石必须正在运行（或将自动启动，这需要时间）
增加超时：设置 OBSIDIAN_CLI_TIMEOUT 更高的值
检查黑曜石是否有反应

MCP未加载

完全重新启动Claude代码
验证虚拟环境是否存在： ./venv/
检查 OBSIDIAN_VAULT_NAME 火柴 obsidian vaults 输出

依赖项

mcp>=1.0.0 -模型上下文协议SDK

注： pyyaml 不再需要——frontmatter是用简单的字符串格式构建的。

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

致谢

专为与以下设备一起使用而构建：

克劳德代码 -AI编码助手
黑曜石 -知识库应用
黑曜石CLI -官方命令行界面
模型上下文协议 -MCP规范