金大哥 - obsidian-api-mcp-server MCP 详情

article

README

🚀 Obsidian MCP Server

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

🚀 快速开始

前提条件

在你的 Obsidian 知识库中安装 Obsidian Local REST API 插件。
在 Obsidian 设置中配置并启用该插件。
记录 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 - 是否递归浏览所有嵌套目录的布尔值

基础搜索示例

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

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

查找标题包含多个术语（OR 逻辑）的笔记：

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

查找标题包含所有指定术语（AND 逻辑）的笔记：

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

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

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

带上下文的文本搜索：

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

按标签搜索：

search_vault(
  tag="project"
)

使用正则表达式进行 OR 条件搜索：

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

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

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 文件。

obsidian-api-mcp-server