使用说明
黑曜石mcp防护装置
用于代理安全黑曜石保险库访问的MCP服务器。提供具有lint验证的读/写文件工具，以防止代理写入格式错误的黑曜石标记。
为什么存在
大多数黑曜石MCP服务器允许代理直接写访问，无需降价验证。那些通过Obsidian REST API路由的人获得了一些输入净化，但没有人在编写之前根据Obsidian的降价呈现规则验证内容。黑曜石mcp卫士填补了这一空白：所有写入在接触保管库之前都会根据黑曜岩的标记规则进行验证，如果内容呈现不正确，则写入会被拒绝，并给出一个结构化错误，解释到底违反了哪条规则。写入也可以限制在单个可配置的保管库路径上，为代理提供指定的空间来代表用户创建和管理内容，同时防止意外或失控地写入同一文件系统上的其他保管库。目录遍历攻击在路径解析层被阻止，因此配置错误、行为不端或提示注入的代理无法通过构建以下路径来逃离写保险库 Claude/../OtherVault/note.md
特性
- 读取/列出/创建/更新/删除/移动 笔记通过
HOST_VAULT_PATH在主机文件系统上 - 棉绒验证 在所有使用 mdlint黑曜岩 --阻止违反黑曜石标记规则的写入（未关闭的维基链接、原始HTML、标准标记链接等）
- 写入保险库隔离 --写入操作被限制在一个可配置的保险库中；在读和写路径上都阻止了目录遍历攻击
- 可组合 —
create_vault_server()返回aFastMCP可以通过以下方式挂载到更大服务器中的实例import_server() - 预验证工具 —
lint_note让代理在提交写入之前检查内容
安装
pip install obsidian-mcp-guard
对于不希望手动安装的Claude Desktop用户， uvx 无需设置即可直接运行：
uvx obsidian-mcp-guard
对于当地发展：
python -m venv .venv
source .venv/bin/activate
pip install -e .
配置
| 环境变量 | 默认值 | 描述 |
|---|---|---|
HOST_VAULT_PATH |
（必填） | 包含Vault作为子目录的目录的绝对路径 |
WRITE_VAULT |
Claude |
唯一允许写入操作的vault的名称 |
预期布局示例 HOST_VAULT_PATH:
/path/to/your/vaults/
Claude/ ← write operations land here
Work/ ← readable but not writable
Personal/ ← readable but not writable
用法
作为独立的stdio服务器
# via the installed CLI entry point
HOST_VAULT_PATH=/path/to/your/vaults obsidian-mcp-guard
# or via python -m
HOST_VAULT_PATH=/path/to/your/vaults python -m obsidian_mcp_guard
Claude桌面/光标配置
{
"mcpServers": {
"obsidian": {
"command": "uvx",
"args": ["obsidian-mcp-guard"],
"env": {
"HOST_VAULT_PATH": "/path/to/your/vaults",
"WRITE_VAULT": "Claude"
}
}
}
}
克劳德代码
claude mcp add obsidian -- uvx obsidian-mcp-guard
传递环境变量 -e:
claude mcp add obsidian -e HOST_VAULT_PATH=/path/to/your/vaults -e WRITE_VAULT=Claude -- uvx obsidian-mcp-guard
安装到另一个FastMCP服务器
from contextlib import asynccontextmanager
from fastmcp import FastMCP
from obsidian_mcp_guard import create_vault_server
@asynccontextmanager
async def lifespan(app):
await app.import_server(create_vault_server(
vault_path="/path/to/your/vaults",
write_vault="Claude"
))
yield
mcp = FastMCP("my-agent", lifespan=lifespan)
@mcp.tool()
def search_notes(...):
...
工具
| 工具 | 说明 |
|---|---|
read_note(source) |
在中返回注释的完整内容 vault/path.md 格式 |
list_notes(vault, folder?, recursive?) |
列出vault或子文件夹中的注释路径 |
create_note(source, content, overwrite?) |
创建注释；被棉绒错误堵塞 |
update_note(source, content, mode?) |
覆盖或附加到注释中；被棉绒错误堵塞 |
delete_note(source) |
将笔记移动到 .trash/ （可收回） |
move_note(source_path, dest_path, create_dirs?) |
在书写保险库中移动笔记；重写所有vault文件中的Wiki链接 |
lint_note(content) |
无需书写即可预验证内容；回报 {valid, errors, warnings} |
发展
make install # install package + test dependencies
make test # run tests with coverage (90% minimum)
make build # build source and wheel distributions
make clean # remove build artefacts and cache files
看 贡献.md 获取完整指南。
相关项目
- mdlint黑曜岩 --lint引擎用于根据Obsidian的渲染规则验证markdown
