Obsidian MCP Tool

一个用于直接操作 Obsidian vault 的 MCP 服务器。它通过本地文件系统读写 Markdown 笔记，并可生成或打开 obsidian://open 链接。

功能

• 获取 vault 信息
• 列出笔记和文件夹
• 创建文件夹
• 读取笔记内容、frontmatter、链接、标签
• 创建、覆盖、追加笔记
• 全文搜索笔记并返回行号和上下文
• 移动或重命名笔记
• 生成并可直接打开 Obsidian 笔记链接
• 可选开启删除笔记

安装

cd Obsidian-MCP-Tool
npm install
npm run build

环境变量

| 变量 | 必填 | 说明 | | --- | --- | --- | | OBSIDIAN_VAULT_PATH | 是 | Obsidian vault 的本地目录路径 | | OBSIDIAN_VAULT_NAME | 否 | vault 名称。设置后 obsidian_open_note 会使用 vault + file URI | | OBSIDIAN_ALLOW_DELETE | 否 | 设置为 true 后才允许 obsidian_delete_note 删除笔记 |

MCP 配置示例

本项目提供了 4 个客户端配置模板：

• codex-config.toml: Codex CLI / Codex IDE / Codex App 可用的 TOML 配置片段
• cursor-config.json: Cursor MCP 配置模板
• trae-config.json: Trae MCP 配置模板
• cc-config.json: Claude Code MCP 配置模板

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": ["-y", "@itkmoon/obsidian-mcp", "--stdio"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/obsidian/vault",
        "OBSIDIAN_VAULT_NAME": "Your Vault Name"
      }
    }
  }
}

可用工具

obsidian_get_vault_info

获取当前配置的 vault 路径、名称、笔记数量、文件夹数量和删除权限状态。

obsidian_list_notes

列出 Markdown 笔记。

参数：

• folder: 可选，vault 内文件夹路径
• recursive: 默认 true
• includeFrontmatter: 默认 false
• limit: 默认 200，最大 1000

obsidian_list_folders

列出 vault 内文件夹。

参数：

• folder: 可选，起始文件夹
• recursive: 默认 true
• limit: 默认 200，最大 1000

obsidian_create_folder

创建文件夹。

参数：

• folderPath: vault 内文件夹路径

obsidian_read_note

读取笔记。notePath 可以省略 .md。

参数：

• notePath: 笔记路径
• includeMetadata: 默认 true

obsidian_write_note

创建或写入笔记。父目录会自动创建。

参数：

• notePath: 笔记路径
• content: Markdown 内容
• createIfNotExists: 默认 true
• overwrite: 默认 true

obsidian_append_note

追加内容到笔记。

参数：

• notePath: 笔记路径
• content: 追加内容
• heading: 可选，追加前创建二级标题
• createIfNotExists: 默认 true

obsidian_delete_note

删除笔记。默认禁用，需要设置 OBSIDIAN_ALLOW_DELETE=true。

参数：

• notePath: 笔记路径

obsidian_search_notes

全文搜索 Markdown 笔记。

参数：

• query: 搜索关键词
• folder: 可选，限制搜索文件夹
• caseSensitive: 默认 false
• limit: 默认 50，最大 500
• contextLines: 默认 1，最大 5

obsidian_move_note

移动或重命名笔记。

参数：

• fromPath: 原笔记路径
• toPath: 目标笔记路径
• overwrite: 默认 false

obsidian_open_note

生成 obsidian://open 链接，可选择直接打开 Obsidian。

参数：

• notePath: 笔记路径
• openInObsidian: 默认 false

设计说明

所有传入路径都会被解析并限制在 OBSIDIAN_VAULT_PATH 内。笔记工具只操作 Markdown 文件，未写 .md 扩展名时会自动补齐。