Skip to main content
Glama
Soleil1043

obsidian-mcp

by Soleil1043
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

obsidian-mcp

CI

一个连接 Obsidian vault 的 MCP（Model Context Protocol）服务器：让 ZCode、Claude Code 等 AI harness 能浏览、搜索、编辑已有笔记，并把生成的内容作为新笔记写入 Obsidian。

  • 直接文件系统访问 vault，无需 Obsidian 运行

  • 10 个细粒度 MCP 工具，stdio transport

  • TypeScript strict 实现，内置防误删/防误改保护与 etag 并发控制

工具清单

工具

功能

关键参数

list_notes

列出目录下的笔记与文件夹（跳过 .obsidian/、.trash/ 等隐藏条目与附件）

folder?

read_note

读取笔记全文（UTF-8 原文，含 frontmatter）+ 大小/修改时间/内容 etag

path

search_notes

关键词全文搜索（纯文本子串，非正则），返回文件/行号/行内容/文件命中总数

query、folder?、case_sensitive?、max_results?

create_note

创建笔记，父目录自动创建

path、content?、overwrite?、if_match?

edit_note

整体覆盖 / 末尾追加 / 精准替换（overwrite / append / replace 三模式）

path、mode、content、old_string?、replace_all?、if_match?

move_note

重命名 / 移动笔记，自动更新指向它的 [[wikilink]] 与 Markdown 相对链接

from、to、if_match?

delete_note

删除笔记（默认进 vault 根 .trash/）

path、permanent?、if_match?

manage_frontmatter

YAML frontmatter 字段管理：get / set / delete（自动创建、删空移除整块、YAML 损坏拒绝写入）

path、action、key?、value?、if_match?

manage_tags

标签管理：list 统计全 vault 标签（frontmatter + 行内 #tag）、add / remove 单篇笔记标签（不影响嵌套子标签与代码块）

action、path?、tags?、folder?、if_match?

create_folder

创建文件夹（父级自动创建，已存在报错，隐藏目录拒绝）

path

所有路径均为 vault 内相对路径（POSIX 风格，如 journal/2026-09-30.md），必须以 .md 结尾。

Related MCP server: Obsidian MCP Server

安全与保护行为

  • 路径穿越防护：..、绝对路径、盘符路径一律拒绝，所有操作限制在 vault 根内

  • 仅 Markdown：非 .md 目标（图片、.canvas 等）拒绝操作

  • 删除可恢复：delete_note 默认移入 vault 根 .trash/（Obsidian 原生可恢复），同名自动加时间戳后缀；permanent=true 才永久删除

  • 编辑防误伤：replace 模式要求片段唯一——未找到或多处匹配时报错且文件不变，需显式 replace_all=true 才全量替换

  • 不静默覆盖：create_note / move_note 遇已存在目标默认报错，覆盖需显式 overwrite=true（move 不提供覆盖）

安装与构建

git clone https://github.com/Soleil1043/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build   # 产物输出 dist/

Node.js ≥ 20。

接入 AI harness

服务器通过 stdio transport 运行，任何支持 MCP 的客户端都可用以下方式接入：

配置项

值

command

node（或 npx obsidian-mcp，发布 npm 后）

args

项目内 dist/index.js 的绝对路径

env

OBSIDIAN_VAULT_PATH = 你的 vault 绝对路径

ZCode / Claude Code 等通用 MCP 配置（JSON）：

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "node",
      "args": ["D:/Code/vibecoding/mcp/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "D:/Obsidian/MyVault"
      }
    }
  }
}

Claude Code CLI：

claude mcp add obsidian-mcp --env OBSIDIAN_VAULT_PATH=D:/Obsidian/MyVault -- node D:/Code/vibecoding/mcp/obsidian-mcp/dist/index.js

手动验证（MCP Inspector）：

npx @modelcontextprotocol/inspector node dist/index.js

环境变量

变量

必填

说明

OBSIDIAN_VAULT_PATH

是

Obsidian vault 的绝对路径，支持 ~ 展开；未设置或路径无效时 server 启动即报错退出

开发

npm test          # 运行全部测试（vitest）
npm run test:watch
npm run build     # tsc 编译到 dist/
src/
├── index.ts        # stdio 入口（E01 启动校验）
├── server.ts       # MCP server 与工具注册
├── vault.ts        # Vault 核心：路径安全与归一化
├── errors.ts       # 统一错误类型
└── tools/          # 每个工具一个文件
tests/              # vitest（单元 + InMemory 协议集成测试）
.agent/             # SDD 项目状态（spec / plan / tasks / progress / decisions）

状态

MVP 已按 SDD 范式完成（spec v1.0，11/11 任务）。需求文档见 .agent/spec.md，技术方案见 .agent/plan.md，构建日志见 .agent/progress.md。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Obsidian MCP Server

    marcelmarais
    A
    license
    Not graded
    quality
    D
    maintenance
    A lightweight server that enables AI assistants like Cursor & Claude to read from and write to Obsidian vaults, allowing actions like creating notes, checking existing content, and managing todos through natural language.
    3,187 npm
    31
    Apache 2.0

  • Obsidian MCP Server

    igorilic
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to interact with Obsidian vaults for creating, reading, searching, and managing notes, daily notes, TODOs, session reports, and backlinks through both stdio and HTTP/SSE transports.
    10
    3,254 npm
    4
    MIT

  • Obsidian MCP Local

    HenriqueCSouzza
    A
    license
    C
    quality
    D
    maintenance
    Enables AI assistants to search, read, create, and modify Markdown notes in local Obsidian vaults directly through filesystem operations. Supports tag-based discovery and frontmatter parsing without requiring Obsidian to be open, facilitating integration with VS Code Copilot via stdio transport.
    5
    11 npm
    4
    MIT