Obsidian API MCP Server

黑曜石MCP服务器

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

为什么这很重要

此服务器将您的黑曜石保险库转换为AI代理的强大知识库，实现复杂的多步骤工作流程，如：

• “从我的‘项目/规划’文件夹中检索标题中包含‘路线图’或‘时间线’的笔记，这些笔记是在4月1日之后创建的，然后分析它们是否有任何阻碍或依赖关系，并参考源笔记进行综合风险评估”

• “查找上个月标记为“研究”或“分析”的所有笔记，扫描其内容以查找不完整的部分或未决问题，然后与我的“团队/专业知识”笔记进行交叉引用，以建议哪些同事可以帮助解决每个差距”

• “从‘领导力/季度’中获取包含‘预算’或‘员工人数’的会议记录的完整内容，分析分配给我部门的行动项目，并创建一个按时间顺序排列的时间线，其中包含源记录参考”

服务器的高级过滤、正则表达式支持和完整的内容检索功能使代理能够执行需要数小时手动完成的精细知识工作。

先决条件

1. 安装 黑名单本地REST API 黑曜石保险库中的插件
2. 在黑曜石设置中配置和启用插件
3. 请注意API URL（默认值： https://localhost:27124)和API密钥，如果您设置了一个

安装

来自PyPI（推荐）

# Install from PyPI
pip install obsidian-api-mcp-server

# Or with 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"
      }
    }
  }
}

来源（发展）

# Clone the repository
git clone https://github.com/pmmvr/obsidian-api-mcp-server
cd obsidian-api-mcp-server

# Install with uv
uv pip install -e .

# Or with pip
pip install -e .

配置

为Obsidian API设置环境变量：

# Required: Obsidian API URL (HTTPS by default)
export OBSIDIAN_API_URL="https://localhost:27124"  # Default

# Optional: API key if you've configured authentication
export OBSIDIAN_API_KEY="your-api-key-here"

重要安全提示：避免硬编码您的 OBSIDIAN_API_KEY 直接写入脚本或将其提交给版本控制。考虑使用 .env 文件（包含在 .gitignore 这个项目）和一个类似图书馆的 python-dotenv 以管理API密钥，或使用由操作系统或shell管理的环境变量。

备注：服务器默认为HTTPS，并禁用本地黑曜石实例常用的自签名证书的SSL证书验证。对于HTTP连接，设置 OBSIDIAN_API_URL="http://localhost:27123".

用法

运行MCP服务器：

obsidian-mcp

可用工具

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

1. search_vault -具有灵活过滤器和完整内容检索的高级搜索：

- query -在笔记内容中搜索文本或正则表达式（可选） - query_type -搜索类型：“文本”（默认）或“正则表达式” - search_in_path -将搜索限制在特定文件夹路径 - title_contains -按笔记标题中的文本过滤（字符串、数组或JSON字符串） - title_match_mode -如何匹配多个术语：“任意”（OR）或“全部”（AND） - tag -按标签过滤（字符串、数组或JSON字符串-搜索frontmatter和内联#标签） - tag_match_mode -如何匹配多个标签：“任意”（OR）或“全部”（AND） - context_length -要返回的内容量（为完整内容设置为高） - include_content -布尔值，用于检索所有匹配笔记的完整内容 - created_since/until -按创建日期筛选 - modified_since/until -按修改日期筛选 - page_size -每页结果 - max_matches_per_file -限制每张钞票的匹配次数

主要特点:

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

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

1. browse_vault_structure -高效地浏览vault目录结构：

- path -要浏览的目录（默认为vault根目录） - include_files -布尔值以包含文件（默认值：False，文件夹仅用于速度） - recursive -用于浏览所有嵌套目录的布尔值

示例用例

基本搜索

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

   search_vault(
     search_in_path="Work/Projects/",
     title_contains="meeting"
   )

1. 查找具有多个标题术语的注释（OR逻辑）：

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

1. 查找包含所有标题术语的注释（AND逻辑）：

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

1. 获取所有内容完整的最近笔记：

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

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

   search_vault(
     query="API documentation",
     search_in_path="Engineering/",
     context_length=500
   )

1. 按标签搜索：

   search_vault(
     tag="project"
   )

1. 正则表达式搜索OR条件：

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

1. Regex搜索分配给特定人员的任务：

   search_vault(
     query="(TODO|FIXME|ACTION).*@(alice|bob)",
     query_type="regex",
     search_in_path="Work/Meetings/"
   )

高级多步骤工作流

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

1. 战略项目分析：

   # Step 1: Get all project documentation
   search_vault(
     search_in_path="Projects/Infrastructure/",
     title_contains=["planning", "requirements", "architecture"],
     title_match_mode="any",
     include_content=True
   )

   # Step 2: Find related technical discussions
   search_vault(
     tag=["infrastructure", "technical-debt"],
     tag_match_mode="any",
     modified_since="2025-04-01",
     include_content=True
   )

*然后，代理可以分析依赖关系、识别风险并建议资源分配*

1. 会议行动项挖掘：

# Get all recent meeting notes with full content
search_vault(
  search_in_path="Meetings/",
  title_contains=["standup", "planning", "retrospective"],
  title_match_mode="any",
  created_since="2025-05-01",
  include_content=True
)

*Agent扫描内容以查找操作项，提取任务，并创建按时间顺序的跟踪*

1. 研究差距分析：

# Find research notes with questions or gaps
search_vault(
  query="(TODO|QUESTION|INVESTIGATE|UNCLEAR)",
  query_type="regex",
  tag=["research", "analysis"],
  tag_match_mode="any",
  include_content=True
)

# Cross-reference with team expertise
search_vault(
  search_in_path="Team/",
  tag=["expertise", "skills"],
  tag_match_mode="any",
  include_content=True
)

*Agent识别知识差距，并建议可以提供帮助的团队成员*

1. 拱顶结构探索：

# Quick organizational overview
browse_vault_structure(recursive=True)

# Deep dive into specific areas
browse_vault_structure(
  path="Projects/CurrentSprint/",
  include_files=True,
  recursive=True
)

1. 基于标签的知识映射：

# Find notes with multiple tags (AND logic)
search_vault(
  tag=["project", "urgent"],
  tag_match_mode="all",
  include_content=True
)

# Find notes with any relevant tags (OR logic)
search_vault(
  tag=["architecture", "design", "implementation"],
  tag_match_mode="any",
  modified_since="2025-04-15"
)

发展

# Install with test dependencies
uv pip install -e ".[test]"

# Run the server
python -m obsidian_mcp.server

# Run tests
uv run behave features/blackbox_tests.feature
# Or use the test runner
python run_tests.py

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。