Obsidian MCP Server

Obsidian MCP 服务

一个 MCP（Model Context Protocol）服务，可通过 Local REST API 插件，让 AI Agent 在你的 Obsidian 库中进行深入的知识发现和分析。

这为何重要

此服务可将你的 Obsidian 库转变为 AI Agent 的强大知识库，支持执行复杂的多步骤工作流，例如：

• “检索我的‘Projects/Planning’文件夹中标题含有‘roadmap’或‘timeline’且创建时间在 4 月 1 日之后的笔记，然后分析其中的阻碍或依赖项，并整理综合风险评估，同时附上来源笔记的引用。”

• “查找上个月所有标记为‘research’或‘analysis’的笔记，检查内容中未完成的部分或待解答的问题，然后与我的‘Team/Expertise’笔记交叉比对，建议哪些同事可以帮助解决各项问题。”

• “获取‘Leadership/Quarterly’中含有‘budget’或‘headcount’的会议笔记的完整内容，分析分配给我所在部门的待办事项，并按时间顺序整理时间线，同时附上来源笔记的引用。”

此服务具备高级筛选、正则表达式支持和完整内容检索能力，使 Agent 能够执行细致的知识工作，而这些工作手动完成可能需要数小时。

先决条件

1. 在你的 Obsidian 库中安装 Obsidian Local REST API 插件
2. 在 Obsidian 设置中配置并启用该插件
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 证书验证，以适配本地 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 字符串——搜索 frontmatter 和行内 #tags）
   • 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="Work/Projects/",
     title_contains="meeting"
   )
   

2. 查找标题中包含多个词条的笔记（OR 逻辑）：

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

3. 查找标题中包含所有词条的笔记（AND 逻辑）：

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

4. 获取所有近期笔记的完整内容：

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

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

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

6. 按标签搜索：

   search_vault(
     tag="project"
   )
   

7. 使用正则表达式搜索 OR 条件：

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

8. 使用正则表达式搜索分配给特定人员的任务：

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

高级多步骤工作流

这些示例展示了 Agent 如何串联复杂的知识发现任务：

9. 战略项目分析：

   # 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
   )
   

   Agent 随后可以分析依赖关系、识别风险并建议资源分配

10. 会议行动项挖掘：

# 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 扫描内容以查找行动项、提取任务分配并创建按时间顺序排列的跟踪记录

11. 研究空白分析：

# 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 识别知识空白，并建议可以提供帮助的团队成员

12. 知识库结构探索：

# Quick organizational overview
browse_vault_structure(recursive=True)

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

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

# 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 许可证授权——详情请参阅 LICENSE 文件。