obsidian-mcp

通过 Obsidian CLI 操控 Obsidian 笔记库的 MCP (Model Context Protocol) 服务器

为什么通过 Obsidian CLI 而不是直接读写本地文件？

1. 保证运行时状态与插件协同：通过 CLI 触发的操作会即时刷新 Obsidian 的内部图谱、Dataview 缓存、标签索引与活动标签页，无需重启或等待文件系统扫描。

2. 绕过 macOS 隐私保护 (TCC)：直接读写外部目录容易受到 macOS 文件夹权限与全盘访问限制，而通过 Obsidian 原生/官方 CLI（与运行中的 Electron 进程通信）无需额外授权。

🛠️ 前置条件

1. Obsidian 桌面端：已安装并保持运行状态。

2. Obsidian CLI：已在系统 PATH 中（如 /opt/homebrew/bin/obsidian）。

   • 可在终端运行 obsidian version 验证安装。

Related MCP server: Obsidian MCP Server

⚙️ 环境变量配置

🚀 快速接入 MCP 客户端

方式一：通过 uvx 直接从 GitHub 加载（推荐，免克隆开箱即用）

无需预先下载代码到本地，uvx 会自动拉取最新仓库并在隔离环境中极速启动。

在 Claude Desktop（claude_desktop_config.json）、Cursor 或 Codex（mcp.json）中添加：

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AkimioJR/obsidian-mcp.git",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT": "MyVault"
      }
    }
  }
}

提示：如需锁定指定分支或版本，可追加 @branch 或 @tag，例如：
git+https://github.com/AkimioJR/obsidian-mcp.git@main

方式二：通过 uv tool install 安装为独立工具（高频使用推荐）

使用 uv tool install 将其安装在独立的隔离环境中，既不污染系统 Python，又能生成全局可执行命令并实现秒级启动：

uv tool install git+https://github.com/AkimioJR/obsidian-mcp.git

安装完成后，系统将获得全局 obsidian-mcp 命令。在 MCP 客户端配置中直接指定可执行程序即可：

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "env": {
        "OBSIDIAN_VAULT": "MyVault"
      }
    }
  }
}

版本升级：后续升级到仓库最新代码只需运行：
uv tool upgrade obsidian-mcp

方式三：通过 pip 从 GitHub 安装

你也可以使用 pip 将其直接安装到当前 Python 环境：

pip install git+https://github.com/AkimioJR/obsidian-mcp.git

在 MCP 客户端配置中直接调用该命令：

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "env": {
        "OBSIDIAN_VAULT": "MyVault"
      }
    }
  }
}

💻 本地开发与调试 (Local Development)

如果你需要对本项目进行二次开发或定制功能：

1. 克隆仓库与安装依赖

git clone https://github.com/AkimioJR/obsidian-mcp.git
cd obsidian-mcp

# 使用 uv 同步并安装所有依赖（包含开发与测试工具）
uv sync

2. 本地直接运行服务

uv run obsidian-mcp

3. 本地开发模式下的 MCP 客户端配置

开发阶段可直接将客户端指向本地源码目录：

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/obsidian-mcp",
        "run",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT": "MyVault"
      }
    }
  }
}

4. 运行单元测试与代码检查

# 执行自动化单元测试（覆盖参数组装、错误防御与 Schema 校验）
uv run pytest

# 静态类型检查 (Type Checking)
uv run ty check src tests

# 代码格式化与规范检查
uv run ruff format .
uv run ruff check .

📦 支持的 MCP 工具清单 (45 项全量 1:1 映射)

所有工具均支持可选的 vault 参数，用于随时指定目标库；所有参数均附带精确的 JSON Schema 描述与类型约束。

1. 笔记与内容 (Notes & Content)

• read: 按文件名或相对路径读取笔记内容。

• create: 创建新笔记，支持指定模板、内容、是否覆盖与打开方式。

• append: 向笔记末尾追加内容。

• prepend: 向笔记开头前置插入内容。

• delete: 删除笔记文件（默认移入回收站，支持永久删除）。

• move: 移动或重命名笔记路径。

• rename: 重命名笔记文件。

• open: 在应用图形界面中聚焦打开笔记。

• random_read: 随机读取一篇笔记。

2. 元数据与属性 (Properties & Frontmatter)

• properties: 列出库或笔记的全部属性概览。

• property_read: 读取指定属性值。

• property_set: 设置属性值（支持 text、list、number、checkbox 等）。

• property_remove: 移除指定属性。

3. 图谱与双链 (Graph & Links)

• backlinks: 获取笔记的反向链接列表（JSON 格式）。

• links: 获取笔记的外向链接列表。

• unresolved: 列出未创建笔记的悬空双链。

• orphans: 列出无反向链接的孤立文件。

• deadends: 列出无外向链接的末端文件。

• outline: 获取笔记的大纲标题层级（JSON 格式）。

• aliases: 列出库中或指定文件的别名。

• wordcount: 统计字数与字符数。

4. 标签与任务 (Tags & Tasks)

• tags: 获取所有标签及其统计分布（JSON 格式）。

• tag: 获取特定标签出现详情。

• tasks: 按状态（已完成/待办）、标签或文件筛选任务。

• task: 切换任务勾选状态或标记完成。

5. 库与工作区 (Vault & Workspace)

• vault: 查询 Vault 基本状态（路径、文件数、体积等）。

• vaults: 列出本机已知的所有 Vault 及绝对路径。

• files: 列出库内文件（支持按文件夹、后缀筛选）。

• folders / obsidian_folder: 查看文件夹结构与详情。

• recents: 列出最近访问的文件。

• bookmarks: 查看书签列表。

• workspace: 查询工作区布局树。

• reload / obsidian_restart / obsidian_version: 重新加载库、重启应用、查询版本。

6. 命令、模板与高级扩展 (Commands & Ext)

• command: 触发执行 Obsidian 内置或插件命令。

• commands: 列出所有可用的命令 ID 列表。

• template_read: 读取模板并支持变量解析。

• template_insert: 将模板插入到当前活跃笔记。

• eval: 在 Obsidian 运行时中执行 JavaScript 代码（高级逃生通道）。

7. 插件管理 (Plugins)

• plugins / obsidian_plugins_enabled: 列出已安装/已启用的插件。

• plugin_enable / obsidian_plugin_disable: 启用或禁用指定插件。