Obsidian Api MCP Server

🚀 Obsidian MCP Server

Obsidian MCP Server 是一个基于模型上下文协议（MCP）的服务器，借助 Obsidian 的 Local REST API 插件，能让 AI 智能体在你的 Obsidian 知识库中进行复杂的知识发现和分析。

🚀 快速开始

前提条件

1. 在你的 Obsidian 知识库中安装 Obsidian Local 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，并禁用对本地 Obsidian 实例常用的自签名证书的 SSL 证书验证。如果需要使用 HTTP 连接，请设置 OBSIDIAN_API_URL="http://localhost:27123"。

运行

启动 MCP 服务器：

obsidian-mcp

✨ 主要特性

这个服务器能将你的 Obsidian 知识库转变为 AI 智能体强大的知识基础，支持复杂的多步骤工作流程，例如：

• “从我的 'Projects/Planning' 文件夹中检索标题包含 'roadmap' 或 'timeline'、且创建于 4 月 1 日之后的笔记，然后分析这些笔记中的任何阻碍或依赖关系，并给出综合的风险评估以及源笔记的引用”
• “查找上个月所有带有 'research' 或 'analysis' 标签的笔记，扫描其内容中的不完整部分或未解决的问题，然后与我的 'Team/Expertise' 笔记进行交叉引用，以建议哪些同事可以帮助解决每个差距”
• “获取 'Leadership/Quarterly' 文件夹中包含 'budget' 或 'headcount' 的会议笔记的完整内容，分析分配给我部门的行动项，并创建一个带有源笔记引用的时间线”

服务器的高级过滤、正则表达式支持和完整内容检索功能，使智能体能够完成那些手动操作需要花费数小时的细致知识工作。

💻 使用示例

可用工具

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

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 条件、不区分大小写的搜索等）。

get_note_content - 获取笔记内容

通过路径检索特定笔记的完整内容和元数据。

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"  # 默认值
)

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/"
)

高级多步骤工作流示例

战略项目分析

# 步骤 1: 获取所有项目文档
search_vault(
  search_in_path="Projects/Infrastructure/",
  title_contains=["planning", "requirements", "architecture"],
  title_match_mode="any",
  include_content=True
)

# 步骤 2: 查找相关技术讨论
search_vault(
  tag=["infrastructure", "technical-debt"],
  tag_match_mode="any",
  modified_since="2025-04-01",
  include_content=True
)

智能体可以进一步分析依赖关系、识别风险并建议资源分配

会议行动项挖掘

# 获取所有近期会议笔记的完整内容
search_vault(
  search_in_path="Meetings/",
  title_contains=["standup", "planning", "retrospective"],
  title_match_mode="any",
  created_since="2025-05-01",
  include_content=True
)

智能体扫描内容以查找行动项，提取分配信息，并创建时间跟踪

研究差距分析

# 查找包含问题或差距的研究笔记
search_vault(
  query="(TODO|QUESTION|INVESTIGATE|UNCLEAR)",
  query_type="regex",
  tag=["research", "analysis"],
  tag_match_mode="any",
  include_content=True
)

# 与团队专业知识进行交叉引用
search_vault(
  search_in_path="Team/",
  tag=["expertise", "skills"],
  tag_match_mode="any",
  include_content=True
)

智能体识别知识差距并建议可以提供帮助的团队成员

知识库结构探索

# 快速查看组织结构
browse_vault_structure(recursive=True)

# 深入查看特定区域
browse_vault_structure(
  path="Projects/CurrentSprint/",
  include_files=True,
  recursive=True
)

基于标签的知识映射

# 查找包含多个标签（AND 逻辑）的笔记
search_vault(
  tag=["project", "urgent"],
  tag_match_mode="all",
  include_content=True
)

# 查找包含任何相关标签（OR 逻辑）的笔记
search_vault(
  tag=["architecture", "design", "implementation"],
  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 文件。