快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

npx obsidian-semantic-mcp

详细介绍

黑曜石语义MCP服务器

🎉 激动人心的消息！ 我们从这个项目中学到了一切，并创造了更好的东西！看看新的 黑曜石MCP插件 -一个直接在vault中运行的原生黑曜石插件，具有改进的性能、简化的设置和增强的功能。我们鼓励您尝试一下！

](https://www.npmjs.com/package/obsidian-semantic-mcp)

面向Obsidian的语义、人工智能优化的MCP服务器，将20个工具整合为5个智能操作，并带有上下文工作流提示。

______________________________________________________________________

🚀 试试我们的新原生插件！

这个MCP服务器教会了我们关于AI与黑曜石集成的宝贵经验。我们应用这些见解来创建 黑曜石MCP插件，它提供：

本机集成：直接在黑曜石内部运行（无外部依赖！）
更好的性能：在没有REST API开销的情况下直接访问保险库
设置更简单：像任何黑社会插件一样安装-没有API密钥或外部服务器
增强功能：完全访问黑曜石的内部API和搜索功能
提高了可靠性：不再有连接问题或超时

👉 获取黑曜石MCP插件

______________________________________________________________________

先决条件

黑曜石已安装在您的计算机上
本地REST API 安装在黑曜石保险库中的插件
克劳德桌面版应用

安装

npm install -g obsidian-semantic-mcp

或者直接与npx一起使用（推荐）：

npx obsidian-semantic-mcp

在npm上查看：https://www.npmjs.com/package/obsidian-semantic-mcp

快速开始

安装黑曜石插件：

- 打开黑曜石设置→ 社区插件 - 浏览并搜索“本地REST API” - 安装本地REST API Adam Coddington的插件 - 启用插件 - 在插件设置中，复制您的API密钥（您需要此密钥进行配置）

配置Claude桌面：

npx命令在Claude Desktop配置中自动使用。将此添加到您的Claude Desktop配置中（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

   {
     "mcpServers": {
       "obsidian": {
         "command": "npx",
         "args": ["-y", "obsidian-semantic-mcp"],
         "env": {
           "OBSIDIAN_API_KEY": "your-api-key-here",
           "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
           "OBSIDIAN_VAULT_NAME": "your-vault-name"
         }
       }
     }
   }

特性

该服务器将传统的MCP工具整合到一个AI优化的语义界面中，使AI代理更容易有效地理解和使用黑曜石操作。

关键利益

简化的界面：5个语义操作，而不是21+个单独的工具
上下文工作流：智能提示引导AI代理执行下一个逻辑操作
状态跟踪：基于令牌的系统可防止无效操作
错误恢复：操作失败时的智能恢复提示
模糊匹配：处理微小变化的弹性文本编辑
片段检索：自动从大文件中返回相关部分以保存令牌

为什么是语义操作？

传统的MCP服务器暴露了许多细粒度的工具（20+），这可能会使AI代理不堪重负，导致工具选择效率低下。我们的语义方法：

将20个工具整合为5个语义操作 基于意图
提供上下文工作流提示 指导下一步行动
使用令牌跟踪状态 （受Petri网启发）防止无意义的建议
提供恢复提示 当操作失败时

5语义操作

vault -文件和文件夹操作

- 行动： list, read, create, update, delete, search, fragments

edit -智能内容编辑

- 行动： window （模糊匹配）， append, patch, at_line, from_buffer

view -内容查看和导航

- 行动： window （结合上下文）， open_in_obsidian

workflow -获取指导建议

- 行动： suggest

system -系统操作

- 行动： info, commands, fetch_web - 注： fetch_web 获取网络内容并将其转换为markdown（仅使用 url 参数）

示例用法

而不是在两者之间做出选择 get_vault_file, get_active_file, read_file_content等，您只需使用：

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "daily-notes/2024-01-15.md"
  }
}

响应包括智能工作流提示：

{
  "result": { /* file content */ },
  "workflow": {
    "message": "Read file: daily-notes/2024-01-15.md",
    "suggested_next": [
      {
        "description": "Edit this file",
        "command": "edit(action='window', path='daily-notes/2024-01-15.md', ...)",
        "reason": "Make changes to content"
      },
      {
        "description": "Follow linked notes",
        "command": "vault(action='read', path='{linked_file}')",
        "reason": "Explore connected knowledge"
      }
    ]
  }
}

国家意识建议

系统跟踪上下文令牌以提供相关建议：

读取文件后 [[links]]，它建议遵循它们
编辑失败后，它提供缓冲区恢复选项
搜索后，它建议优化或阅读结果

高级功能

内容缓冲

这 window 编辑操作会在尝试编辑之前自动缓冲您的新内容。如果编辑失败或您想对其进行优化，可以从缓冲区中检索：

{
  "operation": "edit",
  "action": "from_buffer",
  "params": {
    "path": "notes/meeting.md"
  }
}

模糊窗口编辑

语义编辑器使用模糊匹配来查找和替换内容：

{
  "operation": "edit",
  "action": "window",
  "params": {
    "path": "daily/2024-01-15.md",
    "oldText": "meting notes",  // typo will be fuzzy matched
    "newText": "meeting notes",
    "fuzzyThreshold": 0.8
  }
}

智能PATCH操作

目标特定文档结构：

{
  "operation": "edit",
  "action": "patch",
  "params": {
    "path": "projects/todo.md",
    "operation": "append",
    "targetType": "heading",
    "target": "## In Progress",
    "content": "- [ ] New task"
  }
}

大型文档的片段检索

系统在读取文件时自动使用智能片段检索，在保持相关性的同时显著减少了令牌消耗：

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "large-document.md"
  }
}

返回相关片段而不是整个文件：

{
  "result": {
    "content": [
      {
        "id": "file:large-document.md:frag0",
        "content": "Most relevant section...",
        "score": 0.95,
        "lineStart": 145,
        "lineEnd": 167
      }
    ],
    "fragmentMetadata": {
      "totalFragments": 5,
      "strategy": "adaptive",
      "originalContentLength": 135662
    }
  }
}

片段搜索策略：

自适应的 -TF-IDF关键字匹配（默认用于短查询）
接近 -查找查询词紧密排列的片段
语义 -将文档分为有意义的部分

您可以在vault中明确搜索碎片：

{
  "operation": "vault",
  "action": "fragments",
  "params": {
    "query": "project roadmap timeline",
    "maxFragments": 10,
    "strategy": "proximity"
  }
}

要检索完整文件（需要时），请使用：

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "document.md",
    "returnFullFile": true
  }
}

工作流示例

日常笔记工作流程

创建今天的笔记→ 2. 添加模板→ 3. 链接昨天的笔记

研究工作流程

搜索主题→ 2. 读取结果→ 3. 创建合成笔记→ 4. 链接来源

重构工作流

查找所有提及→ 2. 更新链接→ 3. 重命名/合并笔记

配置

语义工作流提示在中定义 src/config/workflows.json 并且可以根据您的工作流程偏好进行定制。

片段检索配置

片段检索系统在读取文件时自动激活以保存令牌。您可以控制此行为：

默认行为：读取文件时最多返回5个相关片段
完全文件访问：使用 returnFullFile: true 获取完整内容的参数
战略选择：系统根据查询长度自动选择，也可以指定：

- adaptive 用于关键字匹配（1-2个单词的查询） - proximity 用于一起查找相关术语（3-5个单词的查询） - semantic 用于概念组块（较长的查询）

错误恢复

当操作失败时，语义接口提供智能恢复提示：

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File not found: daily/2024-01-15.md",
    "recovery_hints": [
      {
        "description": "Create this file",
        "command": "vault(action='create', path='daily/2024-01-15.md')"
      },
      {
        "description": "Search for similar files",
        "command": "vault(action='search', query='2024-01-15')"
      }
    ]
  }
}

环境变量

服务器自动从 .env 文件（如果存在）。变量可以按优先级顺序设置：

现有环境变量（最高优先级）
.env 当前工作目录中的文件
.env 服务器目录中的文件

所需变量：

OBSIDIAN_API_KEY -本地REST API插件中的API密钥

可选变量：

OBSIDIAN_API_URL -API URL（默认值：https://localhost:27124)

- 支持HTTP（端口27123）和HTTPS（端口27124） - HTTPS使用自动接受的自签名证书

OBSIDIAN_VAULT_NAME -上下文中的保险库名称

示例 .env 文件：

OBSIDIAN_API_KEY=your-api-key-here
OBSIDIAN_API_URL=http://127.0.0.1:27123
OBSIDIAN_VAULT_NAME=MyVault

PATCH操作

PATCH操作(patch_active_file 和 patch_vault_file)允许复杂的内容操作：

目标类型：

- heading：使用“标题1:：副标题”等路径在特定标题下定位内容 - block：目标特定块引用 - frontmatter：目标前沿领域

操作：

- append：在目标后添加内容 - prepend：在目标之前添加内容 - replace：替换目标内容

示例：在特定标题下附加内容：

{
  "operation": "append",
  "targetType": "heading",
  "target": "Daily Notes::Today",
  "content": "- New task added"
}

发展

# Clone and install
git clone https://github.com/aaronsb/obsidian-semantic-mcp.git
cd obsidian-semantic-mcp
npm install

# Development mode
npm run dev

# Testing
npm test              # Run all tests
npm run test:coverage # With coverage report

# Build
npm run build         # Build the server
npm run build:full    # Test + Build

# Start
npm start             # Start the server

建筑

语义系统由以下部分组成：

语义路由器 (src/semantic/router.ts)-将操作发送给处理人员
州代币 (src/semantic/state-tokens.ts)-跟踪上下文状态
工作流配置 (src/config/workflows.json)-定义提示和建议
核心工具 (src/utils/)-共享功能，如文件读取和模糊匹配

测试

该项目包括语义系统的全面Jest测试：

npm test                    # Run all tests
npm test semantic-router    # Test routing logic
npm test semantic-tools     # Test integration

已知问题

搜索功能：由于Obsidian本地REST API插件中的API限制，搜索操作可能偶尔会在大型保管库上超时。

贡献

欢迎投稿！感兴趣的领域：

中的其他工作流模式 workflows.json
新的语义操作
增强状态跟踪
与黑曜石插件集成

许可证

麻省理工学院

目录标签

知识管理TypeScriptClaude工作流自动化本地部署AI集成语义操作笔记工具

支持客户端

Claude DesktopClaude

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

none

运行时（runtime，运行环境）

Node.js

部署方式（deploymentType，部署类型）

local-only

来源包（packageName，安装包名）

obsidian-semantic-mcp

工具数量（toolCount，工具数）

0

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdiononelocal-only

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/52f888061e51ed0e023e76ee4709470c

为Obsidian设计的AI优化语义操作服务器，将20+工具整合为5种智能操作，提供上下文工作流提示和状态跟踪。

OB

Glama

glama.ai

/mcp/servers/aaronsb/obsidian-semantic-mcp

A server that consolidates 21+ Obsidian tools into 5 intelligent operations (vault, edit, view, workflow, system) with contextual workflow hints to help AI agents effectively interact with Obsidian.

继续浏览同类 MCP

更多文档知识 MCP（3,282）返回 MCP 目录

上一个 MCP

Obsidian Semantic MCP

全面解析Obsidian Semantic MCPMCP Server的核心功能、安装配置和实用案例。作为顶级Model Context Protocol服务器，Obsidian Semantic MCP能让AI助手访问实时数据、执行操作，为您提供更智能的工作体验和自动化解决方案。

下一个 MCP

Obsidian Sync MCP

通过MCP协议为AI代理提供对Obsidian知识库的访问，支持本地文件或云端CouchDB同步。

Obsidian Semantic MCP Server