obsidian-mcp (Python)

一个用 Python 编写的 MCP（模型上下文协议）服务器，通过直接文件系统访问，让 LLM 客户端（如 Claude Desktop）能够读写本地 Obsidian 仓库（vault）——不需要 Obsidian Local REST API 插件，不需要 HTTP，也不需要认证令牌。

这是 obsidian-mcp（TypeScript）的 Python 移植版，功能等价，但有几处刻意为之的修复和简化——完整理由见 Plans/review-the-typescript-obsidian-mcp-parsed-shamir.md 和 ISA.md。

警告：此服务器对您的仓库具有读写权限。使用前请备份您的笔记（例如通过 git）。

环境要求

• Python 3.11+

• uv

• 一个 Obsidian 仓库（一个至少被 Obsidian 打开过一次的目录，即包含 .obsidian/app.json）

• macOS 或 Linux（Windows 不受支持——见 ISA「超出范围」）

Related MCP server: Obsidian MCP Server

安装与运行

uv sync
uv run obsidian-mcp /path/to/your/vault [/path/to/another/vault ...]

仓库名称根据每个目录的 basename 自动派生（转为小写，非字母数字字符变为连字符，重复时加数字后缀）。最多支持 10 个仓库；仓库路径之间不能互相嵌套。

Claude Desktop 配置

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/py-obsidian-mcp", "obsidian-mcp", "/path/to/your/vault"]
    }
  }
}

工具

read-note、create-note、edit-note（追加/前置/替换/删除）、delete-note（默认软删除到 .trash/）、move-note、create-directory、search-vault（内容/文件名/标签搜索，可选 max_results）、add-tags、remove-tags、rename-tag（整个仓库范围，保持层级结构）、list-available-vaults。

另外还暴露了一个 obsidian-vault:// 资源方案（仓库列表/信息）和一个 list-vaults 提示。

开发

uv sync --all-extras
uv run pytest -q
uv run ruff check src tests

安全说明

• 每个工具都会校验目标路径保持在仓库范围内（src/obsidian_mcp/utils/path_safety.py），包括感知符号链接的包含检查。

• TypeScript 原版存在一个已确认的 bug：这个包含检查实际上相当于空操作（一个异步验证函数被调用时没有 await）。本移植版的路径安全函数全部是同步的，从根本上防止了这类 bug 的发生。