金大哥 - obsidian-ts-mcp MCP 详情

article

README

🚀 obsidian-ts-mcp

这是一个模型上下文协议（MCP）服务器，它封装了官方的 Obsidian CLI，允许 VS Code（以及其他任何 MCP 客户端）中的 AI 代理读取、写入、搜索和管理 Obsidian 保险库中的笔记。

🚀 快速开始

在使用此 MCP 服务器前，你需要满足以下先决条件： | 要求 | 最低版本 | | ---- | ---- | | Node.js | 18 | | Obsidian 桌面应用 | 1.12（需启用 CLI） | | Obsidian Catalyst 许可证 | 使用 CLI 需要此许可证 |

使用 MCP 服务器时，Obsidian 桌面应用必须处于运行状态，并且 obsidian 二进制文件必须在你的 PATH 中可用。

📦 安装指南

git clone https://github.com/dickiedyce/obsidian-ts-mcp.git
cd obsidian-ts-mcp
npm install
npm run build

📚 详细文档

VS Code（用户级 MCP）

将以下内容添加到你的 VS Code MCP 配置中： | 操作系统 | 路径 | | ---- | ---- | | macOS | ~/Library/Application Support/Code/User/mcp.json | | Linux | ~/.config/Code/User/mcp.json | | Windows | %APPDATA%\Code\User\mcp.json |

{
  "servers": {
    "obsidian": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}

Claude Desktop

将以下内容添加到 claude_desktop_config.json 中（在 macOS 上路径为 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上路径为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}

将 OBSIDIAN_VAULT 设置为你要使用的保险库名称，该名称必须与 Obsidian 保险库切换器中显示的名称完全一致。

环境变量

| 变量 | 描述 | | ---- | ---- | | OBSIDIAN_VAULT | 每个 CLI 调用默认附加的保险库名称。 | | OBSIDIAN_VAULT_PATH | 保险库根目录的绝对文件系统路径。用于直接的文件系统操作；如果未设置，则通过 CLI 解析路径。 |

可用工具

服务器提供了 37 个工具，分为十一个组。

核心 - 笔记管理

| 工具 | 描述 | | ---- | ---- | | create_note | 创建一个新笔记，可选择使用模板。支持 path 参数以精确放置在子目录中。 | | read_note | 读取笔记的完整 Markdown 内容。 | | append_to_note | 在笔记末尾追加内容。 | | prepend_to_note | 在笔记的前置元数据后添加内容。 | | search_vault | 使用 Obsidian 查询语法进行全文搜索。 | | daily_note | 获取或创建今天的每日笔记。 | | daily_append | 在今天的每日笔记末尾追加内容。 |

发现和上下文

| 工具 | 描述 | | ---- | ---- | | get_vault_info | 获取保险库名称、路径、文件/文件夹数量和大小。 | | list_files | 列出文件，可选择按文件夹或扩展名过滤。 | | get_tags | 列出所有标签及其出现次数。 | | get_backlinks | 查找链接到给定笔记的笔记。 | | get_outline | 获取笔记的标题结构。 |

属性和元数据

| 工具 | 描述 | | ---- | ---- | | set_property | 设置笔记的前置元数据属性。 | | read_property | 读取前置元数据属性的值。 |

任务

| 工具 | 描述 | | ---- | ---- | | list_tasks | 列出任务，可按状态、文件或每日笔记进行过滤。 | | toggle_task | 切换任务复选框的状态。 |

每日笔记（扩展）

| 工具 | 描述 | | ---- | ---- | | daily_read | 读取今天的每日笔记内容。 | | daily_prepend | 在每日笔记的前置元数据后添加内容。 |

模板

| 工具 | 描述 | | ---- | ---- | | list_templates | 列出保险库中所有可用的模板。 | | read_template | 读取模板的内容，可选择解析。 |

链接

| 工具 | 描述 | | ---- | ---- | | get_links | 列出笔记的所有出站链接。 |

属性（扩展）

| 工具 | 描述 | | ---- | ---- | | list_properties | 列出保险库中使用的所有前置元数据属性。 | | remove_property | 从笔记中移除前置元数据属性。 |

标签（扩展）

| 工具 | 描述 | | ---- | ---- | | get_tag_info | 获取特定标签及其关联文件的详细信息。 |

文件管理

| 工具 | 描述 | | ---- | ---- | | move_file | 移动或重命名文件；Obsidian 会更新内部链接。 |

数据库

| 工具 | 描述 | | ---- | ---- | | query_base | 查询 Obsidian 数据库并返回结构化结果。 |

项目管理

| 工具 | 描述 | | ---- | ---- | | project_create | 创建一个包含概述和待办事项文件的新项目。 | | project_list | 列出保险库中的所有项目。 | | project_overview | 读取项目的概述元数据。 | | project_context | 加载完整的项目上下文：概述、待办事项、最近会话。 | | project_summary | 生成指定日期范围内项目活动的摘要。 | | project_dashboard | 跨项目仪表板，显示状态、活动和待办事项数量。 | | backlog_add | 向项目的待办事项列表中添加一项。 | | backlog_read | 读取项目的待办事项列表。 | | backlog_done | 使用时间戳将待办事项标记为已完成。 | | backlog_prioritise | 将待办事项重新排序到特定位置。 | | backlog_reorder | 一次重新排序多个待办事项。 |

项目结构

src/
  cli.ts          -- 底层 Obsidian CLI 包装器（执行、参数构建、错误处理）。
  fs-ops.ts       -- 直接的文件系统操作（创建目录、读取、写入），用于精确的路径控制。
  tools.ts        -- MCP 工具定义（名称、描述、JSON 模式）。
  handlers.ts     -- 将工具调用（37 个工具）分派到 CLI 命令或文件系统操作。
  server.ts       -- MCP 服务器入口点（标准输入输出传输、错误处理）。
  validation.ts   -- 根据工具模式进行输入验证。
tests/
  cli.test.ts           -- 参数构建和错误类型的单元测试。
  fs-ops.test.ts        -- 文件系统操作的单元测试。
  runObsidian.test.ts   -- CLI 执行、超时、保险库目标的测试。
  handlers.test.ts      -- 所有 37 个工具处理程序的测试（CLI 和文件系统操作被模拟）。
  tools.test.ts         -- 每个工具定义的模式验证。
  validation.test.ts    -- 输入验证测试（类型、枚举、必填字段）。
  server.test.ts        -- 服务器工厂、错误格式化、版本检查。

开发

npm run dev           # 监听模式下的 TypeScript 编译
npm test              # 运行一次测试套件
npm run test:watch    # 在监听模式下运行测试
npm run test:coverage # 运行测试并生成覆盖率报告
npm run build         # 一次性编译
npm run lint          # 运行 ESLint
npm run format:check  # 检查 Prettier 格式化
npm start             # 在标准输入输出上启动 MCP 服务器

工作原理

MCP 客户端（VS Code、Claude Desktop 等）通过标准输入输出启动服务器。
客户端调用 tools/list 并从 src/tools.ts 接收 37 个工具定义。
当客户端调用工具时，src/server.ts 将调用路由到 src/handlers.ts 中的 handleTool()。
handleTool() 根据工具模式验证输入，然后使用 src/cli.ts 中的 buildArgs() 和 runObsidian() 执行相应的 obsidian CLI 命令，或者在需要精确路径控制时（例如在子目录中创建笔记、项目管理）使用 src/fs-ops.ts 中的直接文件系统操作。
CLI 输出作为文本内容块返回给客户端。

测试

测试使用 Vitest 并模拟 CLI 层，因此它们永远不会调用真正的 Obsidian 二进制文件。运行以下命令进行测试：

npm test

安全考虑

完全保险库访问：服务器对目标保险库中的每个笔记都有读写访问权限。请将 OBSIDIAN_VAULT 限制为你愿意向 AI 代理公开的保险库。
无身份验证：标准输入输出传输没有内置的身份验证。访问控制完全取决于谁可以启动服务器进程。
输入验证：所有工具输入在执行前都会根据其声明的模式进行验证。服务器使用 execFile（而不是 exec）来避免 shell 注入，但请注意，文件/路径值会直接传递给 Obsidian CLI。
环境继承：子进程会继承父进程的环境变量。避免在服务器进程可见的环境变量中存储机密信息。

故障排除

| 症状 | 原因 | 解决方法 | | ---- | ---- | ---- | | obsidian: command not found | CLI 二进制文件不在 PATH 中 | 确保安装了 Obsidian 1.12 或更高版本，并在“设置 > 常规”中启用了 CLI | | Command timed out after 15000ms | Obsidian 桌面应用未运行 | 在使用 MCP 服务器之前启动 Obsidian 应用 | | vault not found | 保险库名称不匹配 | 检查 OBSIDIAN_VAULT 是否与 Obsidian 保险库切换器中的名称完全一致 | | Catalyst licence required | 缺少许可证 | Obsidian CLI 需要 Catalyst 许可证，请在 obsidian.md 购买 | | 服务器立即退出 | Node.js 版本太旧 | 确保 Node.js 版本 >= 18 (node --version) |

📄 许可证

MIT

obsidian-ts-mcp