Obsidian Ts MCP

🚀 obsidian-ts-mcp

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

🚀 快速开始

在使用此 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 Code（用户级 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

将以下内容添加到 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 保险库切换器中显示的名称完全一致。

环境变量

可用工具

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

核心 - 笔记管理

发现和上下文

属性和元数据

任务

每日笔记（扩展）

模板

链接

属性（扩展）

标签（扩展）

文件管理

数据库

项目管理

项目结构

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 服务器

工作原理

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

测试

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

npm test

安全考虑

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

故障排除

📄 许可证

MIT