Obsidian Vault MCP

HTTP Model Context Protocol 服务器，为 AI 代理提供对本地 Obsidian 仓库的受控访问。

专为需要列出、读取、搜索、创建、更新、重命名和谨慎删除 markdown 笔记的代理运行时（Grok 机器人、Claude、OpenClaw、自定义 MCP 客户端）而构建。

功能特性

• 可流式 HTTP MCP 端点（/mcp）

• Bearer / API 密钥认证

• 全仓库模式（ALLOWLIST=*）或文件夹白名单

• 读取工具：list_notes、list_folder、read_note、search_notes

• 写入工具：create_note、append_note、update_note、create_folder、rename_path、delete_path

• 阻止访问 .obsidian、.git、点文件、.env 和密钥材料

• 原子写入 + 大小限制

• 运维健康检查端点：/healthz

Related MCP server: obsidian-autom8

快速开始

npm install
export VAULT_ROOT="/absolute/path/to/your/vault"
export BEARER_TOKEN="$(openssl rand -hex 32)"
export ALLOWLIST="*"
export WRITE_ALLOWLIST="*"
export MODE="read-write"
export PORT=8790
export BIND=127.0.0.1
export PUBLIC_BASE="http://127.0.0.1:8790"
npm start

健康检查：

curl -s http://127.0.0.1:8790/healthz | jq .

环境变量

接受的认证头：

• Authorization: Bearer <token>

• X-Api-Key: <token>

• X-Obsidian-Token: <token>

MCP 工具

读取

• list_notes — 列出 markdown 路径（可选前缀）

• list_folder — 列出文件/目录（recursive 可选）

• read_note — 读取一条笔记 + 简单 frontmatter

• search_notes — 不区分大小写的子字符串搜索

写入（当 MODE=read-write 时）

• create_note — 创建 markdown 笔记（overwrite 可选）

• append_note — 追加到笔记

• update_note — 替换完整笔记

• create_folder — 创建文件夹树

• rename_path — 重命名/移动文件或文件夹

• delete_path — 删除 markdown 文件或文件夹（非空时使用 recursive）

安全：

• 绝不提供 .obsidian、.git、隐藏路径、.env 或密钥文件

• 写入仅限于 .md / .markdown / .txt

• 受保护的顶层结构锚点不能被整体删除

• 仓库中不应包含密钥，此服务器配置也不应提交到 git

反向代理示例（nginx）

location ^~ /obsidian-mcp/ {
  proxy_pass http://127.0.0.1:8790/;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header Authorization $http_authorization;
  proxy_set_header X-Api-Key $http_x_api_key;
  proxy_buffering off;
}

仅通过 HTTPS 暴露，并在 Node 进程上保持 BIND=127.0.0.1。

Grok / 代理提示词片段

You have MCP tools for an Obsidian vault via obsidian-vault-mcp.

Rules:
1. First call list_folder path="" to see top-level structure.
2. Read OBSIDIAN-STRUCTURE.md if present before reorganizing.
3. Prefer append_note for changelogs; do not rewrite history casually.
4. Create notes only as .md under clear topic folders.
5. Never store secrets, tokens, private keys, or .env values.
6. Use search_notes before creating near-duplicate docs.
7. Use rename_path to organize; use delete_path only for clearly obsolete drafts.

安全说明

• 此服务器功能强大。请将 BEARER_TOKEN 视为密码。

• 生产环境中建议使用网络隔离 + 反向代理认证。

• 全仓库写入模式是为受信任的内部代理设计的；对于信任度较低的机器人，请收紧 WRITE_ALLOWLIST。

• 不要提交 .env、令牌或真实的仓库内容。

许可证

MIT