星战科技xingzhan.cloud
返回市场
MCP黑曜石高级服务器

MCP黑曜石高级服务器

作者：ToKiDoO6 星标更新：2025-10-17
安装使用来源：spider==github.com

项目介绍

高级MCP工具用于Obsidian

<p> <a href="https://mseep.ai/app/tokidoo-mcp-obsidian-advanced"> <img src="https://gips1.baidu.com/it/u=3433375118,2050460485&fm=3081&app=3081&f=PNG?w=406&h=180" alt="MseeP.ai 安全评估徽章"> </a>&nbsp;&nbsp; <a href="https://glama.ai/mcp/servers/@ToKiDoO/mcp-obsidian-advanced"> <img src="https://gips1.baidu.com/it/u=4246434957,2691114742&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Glama MCP服务器徽章" width="380" height="200"> </a>&nbsp;&nbsp; <a href="https://smithery.ai/@ToKiDoO/mcp-obsidian-advanced"> <img src="https://smithery.ai/badge/@ToKiDoO/mcp-obsidian-advanced" alt="Smithery徽章" height="56"> </a> </p>

与Obsidian通过本地REST API社区插件进行交互的高级MCP服务器。它赋予AI代理（如Claude）深入理解你的知识库结构、链接和内容的能力——超越基本的读写操作。

关键高级功能，由obsidiantools库提供支持：

  • 发现知识库树结构以映射笔记层次结构
  • 使用NetworkX图分析笔记连接，为LLM友好洞察提供支持
  • 直接从AI执行Obsidian命令
  • 批量读取文件及其元数据和链接详情
  • 访问当前活跃的笔记以获取实时上下文
  • 在新的Obsidian叶中打开笔记/文件，实现无缝编辑

这种设置让AI代理能够与你一起工作，通过高效地导航和增强你的知识库来提高生产力。

组件

工具

该服务器实现了多个工具以与Obsidian进行交互：

核心文件操作

  • obsidian_list_files_in_dir: 列出特定Obsidian目录中的所有文件和目录
  • obsidian_batch_get_files: 返回知识库中一个或多个笔记（.md文件）的内容和元数据
  • obsidian_put_file: 在知识库中创建新文件或更新现有文件的内容
  • obsidian_append_to_file: 将内容追加到知识库中的新文件或现有文件
  • obsidian_patch_file: 根据标题、块引用或frontmatter字段在现有笔记中插入内容
  • obsidian_delete_file: 从知识库中删除文件或目录

搜索操作

  • obsidian_simple_search: 在所有文件中搜索匹配指定文本查询的文档
  • obsidian_complex_search: 使用JsonLogic查询进行复杂搜索，支持'glob'和'regexp'模式匹配

笔记管理

  • obsidian_get_active_note: 获取当前活跃笔记的内容和元数据
  • obsidian_periodic_notes: 获取指定周期（每日、每周、每月、每季度、每年）的当前周期性笔记
  • obsidian_recent_periodic_notes: 获取指定类型周期性笔记的最近记录
  • obsidian_recent_changes: 获取知识库中最近修改的文件
    • 注意：此工具需要安装Dataview社区插件才能正常工作。确保在你的知识库中安装Dataview插件。

知识库分析

  • obsidian_understand_vault: 获取对知识库结构的全面理解，包括目录树和笔记连接的NetworkX图
  • obsidian_open_files: 在新的叶中打开知识库中的一个或多个文件
  • obsidian_list_commands: 列出可以在obsidian界面运行的所有可用命令
  • obsidian_execute_commands: 在obsidian界面执行一个或多个命令

示例提示

首先指示Claude（或其他MCP客户端）使用Obsidian。然后它将始终调用这些工具。例如，

使用如下提示：

  • "扩展我在Obsidian上正在工作的报告中的市场营销部分"
    • Claude将使用obsidian_get_active_note，阅读它，然后编辑笔记。
  • "搜索所有提到Azure CosmosDb的文件，并快速解释它被提及的上下文"
  • "总结最近的会议笔记，并将其放入新的笔记'summary meeting.md'中。添加一个简介，以便我可以通过电子邮件发送。"

配置

环境变量

对于这个MCP服务器，有2个必需的环境变量需要配置：

  • OBSIDIAN_API_KEY: 通过安装Obsidian REST API插件并进入设置获得。
  • OBSIDIAN_VAULT_PATH: 必须设置绝对路径到你的知识库，以便工具（如obsidian_understand_vault）能正常工作。

此外，还有3个可选的环境变量可以更改：

  • OBSIDIAN_HOST: 可以在Obsidian REST API插件设置中更改，默认值为127.0.0.1，即插件默认设置。
  • OBSIDIAN_PORT: 可以在Obsidian REST API插件设置中更改，默认值为27124，即插件默认设置。
  • INCLUDE_TOOLS: 此变量控制哪些工具可供使用。
    • 写入你想要包含的工具名称（如上所述），用逗号分隔。
    • 例如，如果你只想包含obsidian_understand_vault和obsidian_simple_search工具，你可以设置INCLUDE_TOOLS="obsidian_understand_vault,obsidian_simple_search"在.env或服务器配置中。

有两种方式可以配置环境变量与Obsidian REST API密钥。

  1. 添加到服务器配置（推荐）：
{
  "mcp-obsidian-advanced": {
    "command": "uvx",
    "args": [
      "mcp-obsidian-advanced"
    ],
    "env": {
      "OBSIDIAN_API_KEY": "%3Cyour_api_key_here%3E",
      "OBSIDIAN_HOST": "<your_obsidian_host>",
      "OBSIDIAN_PORT": "<your_obsidian_port>",
      "OBSIDIAN_VAULT_PATH": "</path/to/your/vault>",
      "INCLUDE_TOOLS": ""
    }
  }
}

有时Claude可能无法检测到uv / uvx的位置。你可以使用which uvx找到并粘贴上述配置中的完整路径。

  1. 在工作目录中创建一个.env文件，包含以下变量（仅需OBSIDIAN_API_KEY和OBSIDIAN_VAULT_PATH）：
OBSIDIAN_API_KEY=your_api_key_here
OBSIDIAN_HOST=your_obsidian_host
OBSIDIAN_PORT=your_obsidian_port
OBSIDIAN_VAULT_PATH=/path/to/your/vault
INCLUDE_TOOLS=name_of_tool1,name_of_tool2,...

注意：你可以在Obsidian插件配置中找到API密钥、主机和端口 如果未指定，默认端口是27124 如果未指定，默认主机是127.0.0.1

快速开始

安装

通过Smithery安装

要自动安装Claude Desktop的高级Obsidian MCP服务器，请访问Smithery：

npx -y @smithery/cli install @ToKiDoO/mcp-obsidian-advanced --client claude

Obsidian REST API

你需要运行Obsidian REST API社区插件：https://github.com/coddingtonbear/obsidian-local-rest-api

  • 你可以在Obsidian的“社区插件”中搜索并安装它。

安装并在设置中启用它，并复制API密钥。

Claude Desktop

在MacOS中：~/Library/Application\ Support/Claude/claude_desktop_config.json

在Windows中：%APPDATA%/Claude/claude_desktop_config.json

已发布的服务器配置：

{
  "mcpServers": {
    "mcp-obsidian-advanced": {
      "command": "uvx",
      "args": [
        "mcp-obsidian-advanced"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault/"
      }
    }
  }
}

开发/未发布的服务器配置：

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/dir/to/mcp-obsidian-advanced",
        "run",
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault/"
      }
    }
  }
}

开发

obsidiantools库和Obsidian REST API的附加文档

有关obsidiantools库和Obsidian REST API的附加文档可以在docs目录中找到。

  • obsidiantools_in_15_minutes_documentation.md是一个ipynb文件，演示了obsidiantools的使用案例。
  • obsidian_rest_api_documentation.yaml是一个yaml文件，演示了Obsidian REST API的使用案例。

构建

准备打包以供分发：

  1. 同步依赖项并更新锁文件：
uv sync

调试

由于MCP服务器通过stdio运行，调试可能会很困难。为了最佳的调试体验，我们强烈建议使用MCP Inspector。

你可以通过npm使用以下命令启动MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-obsidian-advanced run mcp--obsidian-advanced

启动后，Inspector将显示一个URL，你可以在浏览器中访问该URL以开始调试。

你也可以使用以下命令监视服务器日志：

tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-obsidian-advanced.log