STARWARCLOUD STARWAR.AI
返回市场
黑曜石-api-mcp服务器

黑曜石-api-mcp服务器

作者：pmmvr19 星标更新：2025-05-31
安装使用来源：spider==github.com

项目介绍

Obsidian MCP Server

一个MCP（模型上下文协议）服务器，通过本地REST API插件使AI代理能够在您的Obsidian保险库中执行复杂的知识发现和分析。

<a href="https://glama.ai/mcp/servers/@pmmvr/obsidian-api-mcp-server"> <img width="380" height="200" src="https://gips1.baidu.com/it/u=666470614,495955828&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Obsidian Server MCP服务器" /> </a>

为什么这很重要

此服务器将您的Obsidian保险库转变为强大的知识库，供AI代理使用，支持复杂的多步骤工作流程，例如：

  • “从我的‘项目/规划’文件夹中检索包含‘路线图’或‘时间线’标题的笔记，创建日期在4月1日之后，然后分析它们以识别任何阻碍或依赖关系，并提供带有来源笔记引用的综合风险评估”

  • “查找过去一个月内标记为‘研究’或‘分析’的所有笔记，扫描其内容以查找未完成的部分或开放问题，然后与我的‘团队/专长’笔记进行交叉引用，建议哪些同事可以帮助解决每个差距”

  • “获取‘领导/季度’文件夹中包含‘预算’或‘员工人数’的会议笔记的全部内容，分析分配给我们部门的操作项，并创建带有来源笔记引用的时间轴”

服务器的高级过滤、正则表达式支持和全文检索功能允许代理执行需要数小时手动操作的复杂知识工作。

先决条件

  1. 在您的Obsidian保险库中安装Obsidian本地REST API插件
  2. 在Obsidian设置中配置并启用该插件
  3. 记录API URL（默认：https://localhost:27124）以及您设置的API密钥（如果有的话）

安装

从PyPI（推荐）

# 从PyPI安装
pip install obsidian-api-mcp-server

# 或使用uv
uv pip install obsidian-api-mcp-server

添加到MCP配置

添加到您的MCP客户端配置（例如，Claude Desktop）：

{
  "mcpServers": {
    "obsidian-api-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "obsidian-api-mcp-server>=1.0.1",
        "obsidian-api-mcp"
      ],
      "env": {
        "OBSIDIAN_API_URL": "https://localhost:27124",
        "OBSIDIAN_API_KEY": "your-api-key-here"
      }
    }
  }
}

从源代码（开发）

# 克隆仓库
git clone https://github.com/pmmvr/obsidian-api-mcp-server
cd obsidian-api-mcp-server

# 使用uv安装
uv pip install -e .

# 或使用pip
pip install -e .

配置

设置环境变量用于Obsidian API：

# 必需：Obsidian API URL（默认为HTTPS）
export OBSIDIAN_API_URL="https://localhost:27124"  # 默认值

# 可选：如果您已配置身份验证，则设置API密钥
export OBSIDIAN_API_KEY="your-api-key-here"

重要安全提示：避免将OBSIDIAN_API_KEY直接硬编码到脚本中或提交到版本控制。考虑使用.env文件（该项目的.gitignore中包括了这个文件）和类似python-dotenv的库来管理您的API密钥，或者使用操作系统或shell管理的环境变量。

注意：服务器默认使用HTTPS，并禁用自签名证书的SSL证书验证，这些证书通常用于本地Obsidian实例。对于HTTP连接，请设置OBSIDIAN_API_URL="http://localhost:27123"。

使用方法

运行MCP服务器：

obsidian-mcp

可用工具

服务器提供了三个强大的工具：

  1. search_vault - 具有灵活过滤器和全文检索的高级搜索：

    • query - 跨笔记内容的文本或正则表达式搜索（可选）
    • query_type - 搜索类型：“text”（默认）或“regex”
    • search_in_path - 限制特定文件夹路径的搜索
    • title_contains - 根据笔记标题中的文本筛选（字符串、数组或JSON字符串）
    • title_match_mode - 多个术语的匹配方式：“any”（OR）或“all”（AND）
    • tag - 根据标签筛选（字符串、数组或JSON字符串 - 搜索前言和内联#标签）
    • tag_match_mode - 多个标签的匹配方式：“any”（OR）或“all”（AND）
    • context_length - 返回的内容量（设置高值以返回全文）
    • include_content - 布尔值，用于检索所有匹配笔记的完整内容
    • created_since/until - 根据创建日期筛选
    • modified_since/until - 根据修改日期筛选
    • page_size - 每页结果数量
    • max_matches_per_file - 每个笔记的匹配限制

    关键特性：

    • 当未提供query时，自动返回仅筛选搜索的全文内容
    • include_content=True强制检索任何搜索的全文内容
    • 支持复杂的文本匹配正则表达式模式（OR条件、不区分大小写的搜索等）

  2. get_note_content - 根据路径检索特定笔记的完整内容和元数据

  3. browse_vault_structure - 高效地浏览保险库目录结构：

    • path - 要浏览的目录（默认为保险库根目录）
    • include_files - 布尔值，是否包含文件（默认：False，仅文件夹以提高速度）
    • recursive - 布尔值，是否浏览所有嵌套目录

示例用例

基础搜索

  1. 按标题在特定文件夹中查找笔记：

    search_vault(
  search_in_path="工作/项目/",
  title_contains="会议"
)

  2. 具有多个标题术语的笔记查找（OR逻辑）：

    search_vault(
  title_contains=["foo", "bar", "fizz", "buzz"],
  title_match_mode="any"  # 默认
)

  3. 具有所有标题术语的笔记查找（AND逻辑）：

    search_vault(
  title_contains=["项目", "2024"],
  title_match_mode="all"
)

  4. 获取所有最近的笔记及其完整内容：

    search_vault(
  modified_since="2025-05-20",
  include_content=True
)

  5. 带上下文的文本搜索：

    search_vault(
  query="API文档",
  search_in_path="工程/",
  context_length=500
)

  6. 按标签搜索：

    search_vault(
  tag="项目"
)

  7. 正则表达式搜索以实现OR条件：

    search_vault(
  query="foo|bar",
  query_type="regex",
  search_in_path="项目/"
)

  8. 针对特定人员的任务正则表达式搜索：

    search_vault(
  query="(TODO|FIXME|ACTION).*@(alice|bob)",
  query_type="regex",
  search_in_path="工作/会议/"
)

高级多步工作流

这些示例展示了代理如何将复杂的知识发现任务链接在一起：

  1. 战略项目分析：

    # 第一步：获取所有项目文档
search_vault(
  search_in_path="项目/基础设施/",
  title_contains=["规划", "需求", "架构"],
  title_match_mode="any",
  include_content=True
)

# 第二步：查找相关的技术讨论
search_vault(
  tag=["基础设施", "技术债务"],
  tag_match_mode="any",
  modified_since="2025-04-01",
  include_content=True
)

    代理可以分析依赖关系，识别风险，并推荐资源分配

  2. 会议行动项挖掘：

# 获取所有近期会议笔记及其完整内容
search_vault(
  search_in_path="会议/",
  title_contains=["站会", "规划", "回顾"],
  title_match_mode="any",
  created_since="2025-05-01",
  include_content=True
)

代理扫描内容以查找行动项，提取分配，并创建时间轴跟踪

  1. 研究缺口分析：
# 查找具有问题或缺口的研究笔记
search_vault(
  query="(TODO|QUESTION|INVESTIGATE|UNCLEAR)",
  query_type="regex",
  tag=["研究", "分析"],
  tag_match_mode="any",
  include_content=True
)

# 与团队专长进行交叉引用
search_vault(
  search_in_path="团队/",
  tag=["专长", "技能"],
  tag_match_mode="any",
  include_content=True
)

代理识别知识缺口，并建议可以帮助解决问题的团队成员

  1. 保险库结构探索：
# 快速组织概述
browse_vault_structure(recursive=True)

# 对特定区域深入研究
browse_vault_structure(
  path="项目/当前冲刺/",
  include_files=True,
  recursive=True
)
  1. 基于标签的知识映射：
# 查找具有多个标签的笔记（AND逻辑）
search_vault(
  tag=["项目", "紧急"],
  tag_match_mode="all",
  include_content=True
)

# 查找具有任何相关标签的笔记（OR逻辑）
search_vault(
  tag=["架构", "设计", "实施"],
  tag_match_mode="any",
  modified_since="2025-04-15"
)

开发

# 安装测试依赖
uv pip install -e ".[test]"

# 运行服务器
python -m obsidian_mcp.server

# 运行测试
uv run behave features/blackbox_tests.feature
# 或使用测试运行器
python run_tests.py

许可证

本项目根据MIT许可证发布 - 详情见LICENSE文件。