AI导哈

Obsidian MCP服务器

一个基于TypeScript的Obsidian MCP服务器，提供核心保险库操作、图形分析和语义搜索功能。

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

使用说明

黑曜石MCP服务器

用于黑曜石的TypeScript MCP服务器，具有核心保险库操作、图形分析和语义搜索功能。

特性

  • 核心工具：读取、写入、搜索、追加、删除黑曜石保管库中的文件
  • 定期注意事项：访问每日、每周、每月的笔记和最近的更改
  • 高级搜索：用于复杂过滤的JsonLogic查询
  • 图形工具：孤儿检测、中心性分析、聚类检测、路径查找
  • 语义搜索：智能连接集成，用于基于概念的搜索

先决条件

安装

来自npm

npm install -g @connorbritain/obsidian-mcp-server

来源

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

配置

设置以下环境变量：

变量 必填 默认 描述
OBSIDIAN_API_KEY 是* - Local REST API插件设置中的API密钥（未提供多保险库JSON时使用）
OBSIDIAN_HOST 没有 127.0.0.1 黑名单REST API主机
OBSIDIAN_PORT 没有 27124 黑名单REST API端口
OBSIDIAN_PROTOCOL 没有 https http 或 https
OBSIDIAN_VAULT_PATH 无 - vault路径（图形工具需要）
SMART_CONNECTIONS_PORT 没有 - 智能连接API端口
GRAPH_CACHE_TTL 没有 300 图形缓存TTL（秒）
OBSIDIAN_VAULTS_JSON 没有描述一个或多个保管库的JSON字符串。超越单曲 OBSIDIAN_API_KEY 样式配置。
OBSIDIAN_VAULTS_FILE 否 - 描述一个或多个Vault的JSON文件的路径（形状与 OBSIDIAN_VAULTS_JSON).
OBSIDIAN_DEFAULT_VAULT 否 首次定义 工具调用省略时要使用的vault的名称/ID vaultId.

多保险库备注： 如果两者都没有 OBSIDIAN_VAULTS_JSON 也不 OBSIDIAN_VAULTS_FILE 提供了传统的单vault环境变量(OBSIDIAN_API_KEY, OBSIDIAN_HOST等等）用于创建 default 自动进入保险库。

示例 OBSIDIAN_VAULTS_JSON

[
  {
    "id": "work",
    "apiKey": "work-api-key",
    "host": "127.0.0.1",
    "port": 27124,
    "protocol": "https",
    "vaultPath": "C:/Users/you/Obsidian/work",
    "smartConnectionsPort": 29327
  },
  {
    "id": "personal",
    "apiKey": "personal-api-key",
    "vaultPath": "C:/Users/you/Obsidian/personal"
  }
]

MCP服务器中的每个工具现在都接受一个可选 vaultId 争论。如果省略，服务器将使用 OBSIDIAN_DEFAULT_VAULT （或第一个定义的保险库）。这允许单个MCP会话通过在工具调用中指定要针对的vault来读取/写入多个vault。

多保险库端口配置

重要提示： 当同时运行多个黑社会保险库时，每个保险库的本地REST API插件必须监听 唯一端口。默认情况下，所有保管库都使用端口 27124，这会导致冲突——一次只能有一个保管库绑定到一个端口，对其他保管库的请求将因授权错误而失败。

步骤1：在黑曜石中分配唯一端口

对于每个保险库，打开 设置→ 社区插件→ 本地REST API 并滚动至 高级设置:

  1. 集 加密（HTTPS）服务器端口 转换为唯一值（例如。， 27124, 27125, 27126, 27127)
  2. 关闭并重新打开插件（或重新启动Obsidian）以应用更改
  3. 复制 API密钥 如插件设置所示

步骤2：更新您的Vault JSON

在你的 obsidian-vaults.json 文件（或 OBSIDIAN_VAULTS_JSON env-var），指定 port 对于每个vault，要匹配您在插件中配置的内容：

[
  {
    "id": "vault_one",
    "apiKey": "your-api-key-for-vault-one",
    "port": 27124,
    "vaultPath": "C:/Users/you/Obsidian/vault_one"
  },
  {
    "id": "vault_two",
    "apiKey": "your-api-key-for-vault-two",
    "port": 27125,
    "vaultPath": "C:/Users/you/Obsidian/vault_two"
  },
  {
    "id": "vault_three",
    "apiKey": "your-api-key-for-vault-three",
    "port": 27126,
    "vaultPath": "C:/Users/you/Obsidian/vault_three"
  }
]

步骤3：重新启动MCP客户端

更新JSON文件后，重新启动MCP客户端（Windsurf、Claude Desktop等），使其使用新端口重新加载配置。

验证连接

您可以使用curl直接测试每个vault的API：

# Replace PORT and API_KEY for each vault
curl -k -H "Authorization: Bearer YOUR_API_KEY" https://127.0.0.1:PORT/vault/

成功的响应将返回一个包含vault文件列表的JSON对象。如果你收到 40101 Authorization required，API密钥不匹配。如果你收到 40400 Not Found，插件未在该端口上完全初始化——请尝试将其关闭/打开或重新启动vault。

MCP客户端配置

使用npx（推荐）

使用 npx 对于最简单的设置：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@connorbritain/obsidian-mcp-server"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_VAULTS_FILE": "C:/path/to/vaults.json",
        "OBSIDIAN_DEFAULT_VAULT": "work"
      }
    }
  }
}

使用本地构建（开发）

如果从源代码运行：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_VAULTS_JSON": "[{\"id\":\"work\",\"apiKey\":\"...\",\"vaultPath\":\"/work\"}]"
      }
    }
  }
}

配置文件位置

客户端 配置路径
克劳德桌面（Windows） %APPDATA%\Claude\claude_desktop_config.json
克劳德桌面（Mac/Linux） ~/.config/claude/claude_desktop_config.json
帆板运动 ~/.windsurf/mcp_config.json
光标 ~/.cursor/mcp_config.json

可用工具

所有工具都接受可选 vaultId 争论。如果省略，服务器将使用配置中的默认vault。这使您可以在同一MCP会话中读/写多个黑曜石保管库。

保险库管理

工具 说明
list_vaults 列出所有已配置的保管库及其ID、功能和连接信息

核心文件操作

工具 说明
list_files_in_vault 列出vault根目录中的所有文件/目录
list_files_in_dir 列出特定目录中的文件
get_file_contents 读取单个文件
batch_get_file_contents 读取与标头连接的多个文件
delete_file 删除文件或目录

写入操作

工具 说明
append_content 附加到文件（如果丢失则创建）
put_content 覆盖文件内容
patch_content ⚠️ 残疾：插入相对于标题/块的内容（正在等待Obsidian REST API修复- 见第146期)

备注：The patch_content 由于Obsidian本地REST API插件中的已知错误，该工具当前被禁用。使用读-修改-写模式 get_file_contents + put_content 作为一种可靠的替代方案。

搜索

工具 说明
search 跨vault的关键字搜索
complex_search JsonLogic查询搜索（glob、regexp支持）
pattern_search 基于上下文的正则表达式模式提取 （需要vault路径）

定期注释和最近更改

工具 说明
get_periodic_note 获取当前的每日/每周/每月/每季度/每年注释
get_recent_periodic_notes 获取包含可选内容的最新定期笔记
get_recent_changes 获取最近修改的文件（需要Dataview）

黑曜石融合

工具 说明
get_active_file 获取黑曜石中当前活动的文件
open_file 在黑曜石中打开文件
list_commands 列出所有可用的黑曜石命令
execute_command 执行一个或多个黑曜石命令

图形工具 （需要OBSIDIAN_VAULT_PATH）

工具 说明
get_vault_stats 概述统计数据（注释、链接、孤儿、集群）
find_orphan_notes 没有传入/传出链接的笔记
get_note_connections 传入/传出链接+注释标签
find_path_between_notes 两个音符之间的最短链接路径
get_most_connected_notes 按链接数或PageRank排列的热门笔记
detect_note_clusters 通过图形分析进行社区检测
get_vault_structure vault的文件夹树结构

语义工具 （需要智能连接插件）

工具 说明
semantic_search 通过智能连接进行概念搜索
find_similar_notes 查找语义相似的注释

发展

# Watch mode
npm run dev

# Type check
npm run typecheck

# Build
npm run build

许可证

麻省理工学院

相关 MCP