Skip to main content
Glama
obsidian-vault-mcp

obsidian-vault-mcp

by JulioMCruz

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_mcp

快速开始

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 .

环境变量

变量

必需

默认值

描述

VAULT_ROOT

是

—

Obsidian 仓库的绝对路径

BEARER_TOKEN

是

—

MCP 客户端的共享密钥

ALLOWLIST

否

示例文件夹

相对文件夹的逗号分隔列表,或 * 表示整个仓库

WRITE_ALLOWLIST

否

与 ALLOWLIST 相同

写入范围;* = 整个仓库(仍阻止密钥/点文件)

MODE

否

read-write

read-write 或 read-only

PORT

否

8790

监听端口

BIND

否

127.0.0.1

绑定地址

PUBLIC_BASE

否

http://127.0.0.1:8790

在元数据中公布的公共基础 URL

MAX_SEARCH_HITS

否

25

搜索结果上限

MAX_FILE_BYTES

否

400000

读取的最大笔记大小

MAX_WRITE_BYTES

否

350000

写入的最大笔记大小

接受的认证头:

  • 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables reading, writing, searching, and managing Obsidian vault notes through MCP tools and prompts, allowing AI agents to interact with local knowledge bases.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to search, read, list, and append to markdown notes in a local Obsidian vault or folder of .md files.
      -