Obsidian TS MCP

黑曜岩ts-mcp

封装官方黑曜石CLI的模型上下文协议（MCP）服务器， 让VS Code中的AI代理（以及任何其他MCP客户端）读取、写入、搜索、， 并管理黑曜石金库内的笔记。

先决条件

MCP服务器使用时，Obsidian桌面应用程序必须正在运行。 这 obsidian 二进制文件必须在您的 PATH.

安装

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

配置

VS代码（用户级MCP）

将以下内容添加到VS Code MCP配置中：

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

克劳德桌面版

添加 claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上， %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

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

集 OBSIDIAN_VAULT 指向您要定位的保险库的名称。名称 必须与黑曜石在跳马切换器中显示的完全匹配。

环境变量

可用工具

服务器公开了39个工具，分为11组。

核心--笔记管理

发现和背景

属性和元数据

任务

每日笔记（扩展）

模板

链接

属性（扩展）

标签（扩展）

文件管理

基础

项目管理

由创建的待办事项列表条目 backlog_add 现在包括一个稳定 [#] 标记。

项目结构

src/
  cli.ts          -- Low-level Obsidian CLI wrapper (exec, arg building, errors).
  fs-ops.ts       -- Direct filesystem operations (mkdir, read, write) for exact path control.
  tools.ts        -- MCP tool definitions (names, descriptions, JSON schemas).
  handlers.ts     -- Dispatches tool calls (39 tools) to CLI commands or filesystem ops.
  server.ts       -- MCP server entry-point (stdio transport, error handling).
  validation.ts   -- Input validation against tool schemas.
tests/
  cli.test.ts           -- Unit tests for argument building and error types.
  fs-ops.test.ts        -- Unit tests for filesystem operations.
  runObsidian.test.ts   -- Tests for CLI execution, timeouts, vault targeting.
  handlers.test.ts      -- Tests for all 37 tool handlers (CLI and fs-ops are mocked).
  tools.test.ts         -- Schema validation for every tool definition.
  validation.test.ts    -- Input validation tests (types, enums, required fields).
  server.test.ts        -- Server factory, error formatting, version checks.

发展

npm run dev           # Watch-mode TypeScript compilation
npm test              # Run the test suite once
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run build         # One-shot compilation
npm run lint          # Run ESLint
npm run format:check  # Check Prettier formatting
npm start             # Start the MCP server on stdio

运作原理

1. MCP客户端（VS Code、Claude Desktop等）通过以下方式启动服务器

停下来

1. 客户来电 tools/list 并从接收37个工具定义

src/tools.ts.

1. 当客户端调用工具时， src/server.ts 将呼叫路由到

handleTool() 在 src/handlers.ts.

1. handleTool() 根据工具模式验证输入，然后使用

buildArgs() 和 runObsidian() 从 src/cli.ts 执行 相应的 obsidian CLI命令，或使用直接文件系统 操作从 src/fs-ops.ts 当需要精确的路径控制时 （例如在子目录中创建注释、项目管理）。

1. CLI输出作为文本内容块返回给客户端。

测试

测试使用Vitest并模拟CLI层，因此它们永远不会调用真正的 黑曜石双星。运行：

npm test

安全注意事项

• 完全访问保险库。 服务器对中的每个笔记都有读/写权限

目标金库。限制 OBSIDIAN_VAULT 去保险库你会很舒服 暴露于AI代理。

• 没有身份验证。 stdio传输没有内置身份验证。访问

控制完全取决于谁可以启动服务器进程。

• 输入验证。 所有工具输入均根据其声明进行验证

执行前的模式。服务器使用 execFile （不是 exec)为了避免 shell注入，但请注意，文件/路径值直接传递给 黑曜石CLI。

• 环境继承。 子进程继承父进程的

环境变量。避免将机密存储在对 服务器进程。

故障排除

症状 : obsidian: command not found\ 原因：CLI二进制文件不在PATH上\ 修复：确保安装了Obsidian 1.12+，并在“设置”>“常规”中启用了CLI

症状 : Command timed out after 15000ms\ 原因：黑曜石桌面应用程序未运行\ 修复：在使用MCP服务器之前启动Obsidian应用程序

症状 : vault not found\ 原因：保险库名称不匹配\ 修复：检查一下 OBSIDIAN_VAULT 与黑曜石金库切换器中的确切名称匹配

症状 : Catalyst licence required\ 原因：缺少许可证\ 修复：黑曜石CLI需要Catalyst许可证，请在Obsidian.md购买

症状 ：服务器立即退出\ 原因：Node.js版本太旧\ 修复：确保Node.js>=18(node --version)

许可证

麻省理工学院