AI导哈

Obsidian MCP 服务器

一个为AI代理提供通过Obsidian CLI读写Obsidian保险库访问权限的模型上下文协议（MCP）服务器。

  • by theoryzhenkov
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 theoryzhenkov/obsidian-mcp

使用说明

黑曜石MCP服务器

一种模型上下文协议（MCP）服务器，通过官方的Obsidian CLI（v1.12+）为AI代理提供对Obsidian保管库的读/写访问权限。

特性

  • 19个MCP工具 涵盖vault管理、文件操作、搜索、标记、属性、任务、链接、模板、插件等
  • 资源模板 用于将vault文件作为MCP资源浏览
  • 类型安全 带有Zod验证的TypeScript实现
  • 共享助手 消除跨工具的样板文件
  • 验证防护装置 防止因缺少参数而导致的运行时错误

先决条件

安装

全局安装（推荐）

claude mcp add obsidian-mcp --scope user -- bun run /path/to/obsidian-mcp/src/index.ts

对于特定的保险库：

claude mcp add obsidian-mcp --scope user \
  --env OBSIDIAN_VAULT=YourVaultName \
  -- bun run /path/to/obsidian-mcp/src/index.ts

本地开发

git clone https://github.com/yourusername/obsidian-mcp.git
cd obsidian-mcp
bun install
bun run src/index.ts

配置

设置这些环境变量以自定义行为：

  • OBSIDIAN_VAULT --默认vault名称（可选，如果未设置，则使用活动vault）
  • OBSIDIAN_CLI_PATH --通往 obsidian 二进制（默认为 "obsidian")

可用工具

保险库管理

  • obsidian_vault --获取保险库信息或列出所有保险库

文件操作

  • obsidian_files --列出文件/文件夹或获取特定项目的信息
  • obsidian_read --读取文件内容
  • obsidian_write --写入或替换完整文件内容
  • obsidian_create --使用可选模板创建新文件
  • obsidian_edit --添加或预置内容
  • obsidian_manage_file --移动或删除文件

搜索与发现

  • obsidian_search --带过滤器的全文搜索
  • obsidian_tags --列出标签或按标签查找注释
  • obsidian_links --分析反向链接、传出链接、孤立链接、未解析链接、死端

元数据和结构

  • obsidian_properties --前端属性的CRUD操作
  • obsidian_outline --获取笔记的标题结构
  • obsidian_tasks --列出或更新任务

每日笔记和模板

  • obsidian_daily --阅读或修改今天的每日笔记
  • obsidian_templates --列出或阅读模板

保险库功能

  • obsidian_bookmarks --列出书签项目
  • obsidian_plugins --管理社区插件
  • obsidian_workspace --管理工作空间布局
  • obsidian_command --运行任意黑曜石命令

用法示例

读便条

// Using obsidian_read tool
{
  "path": "Projects/AI Research.md"
}

将内容写入文件

// Using obsidian_write tool
{
  "path": "Daily/2026-02-17.md",
  "content": "# Meeting Notes\n\n- Discussed MCP server architecture"
}

搜索保险库

// Using obsidian_search tool
{
  "query": "machine learning",
  "path": "Projects",
  "limit": 10
}

添加到每日笔记中

// Using obsidian_daily tool
{
  "action": "append",
  "content": "\n## New Section\n\nContent here"
}

建筑

obsidian-mcp/
├── src/
│   ├── index.ts              # Entry point, server setup
│   ├── cli.ts                # ObsidianCLI wrapper class
│   ├── config.ts             # Environment-based configuration
│   ├── helpers.ts            # Shared response/validation helpers
│   ├── tools/
│   │   ├── index.ts          # Tool registration barrel
│   │   └── *.ts              # 19 individual tool modules
│   └── resources/
│       └── vault.ts          # Resource template for vault files
├── package.json
├── tsconfig.json
└── CLAUDE.md                 # Project-specific AI instructions

发展

命令

# Run server
bun run src/index.ts

# Build
bun build src/index.ts --outdir dist --target bun

# Type check
bunx tsc --noEmit

# Test with MCP Inspector
bunx @modelcontextprotocol/inspector bun run src/index.ts

添加新工具

  1. 创建 src/tools/your_tool.ts:
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import type { ObsidianCLI } from "../cli.js";
import { cliResponse } from "../helpers.js";

export function register(server: McpServer, cli: ObsidianCLI): void {
  server.tool(
    "obsidian_your_tool",
    "Tool description for AI agents",
    {
      param: z.string().describe("Parameter description"),
    },
    async ({ param }) => {
      const result = await cli.exec("command", { param });
      return cliResponse(result);
    },
  );
}
  1. 注册于 src/tools/index.ts:
import { register as yourTool } from "./your_tool.js";
// Add to registrations array

运作原理

服务器通过官方CLI与Obsidian通信，CLI使用IPC与正在运行的桌面应用程序进行交互。每个工具都封装了一个特定的CLI命令，根据MCP规范处理参数验证、错误响应和输出格式。

关键部件：

  • 黑曜石CLI --产卵 obsidian 具有正确参数格式的进程
  • 共享助手 — cliResponse(), errorResponse(), fileOrPathSchema等等。
  • 验证防护装置 --在CLI调用之前显式检查条件参数
  • 资源模板 --将vault文件作为可浏览的MCP资源公开

局限性

  • 需要运行Obsidian桌面应用程序（CLI使用IPC）
  • 没有直接的文件系统访问权限（所有操作都通过Obsidian CLI进行）
  • 某些操作可能比直接操作文件慢

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支(jj new 或 git checkout -b feature/amazing-feature)
  3. 通过测试进行更改
  4. 提交拉取请求

许可证

麻省理工学院©[你的名字]

资源

更新日志

0.1.0 (2026-02-17)

  • 初始版本
  • 涵盖黑曜石核心业务的19个MCP工具
  • 用于浏览vault文件的资源模板
  • 共享助手和验证保护

相关 MCP