Obsidian MCP 服务器

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

为什么这很重要

该服务器将您的 Obsidian 库转变为 AI 代理的强大知识库，从而实现复杂的多步骤工作流程，例如：

“从我的‘项目/计划’文件夹中检索 4 月 1 日之后创建的包含‘路线图’或‘时间线’标题的笔记，然后分析它们是否存在任何阻碍因素或依赖关系，并参考源笔记提供综合风险评估”
“查找上个月所有带有‘研究’或‘分析’标签的笔记，扫描其内容以查找未完成的部分或未解决的问题，然后与我的‘团队/专业知识’笔记进行交叉引用，以建议哪些同事可以帮助解决每个差距”
“从‘领导/季度’中获取包含‘预算’或‘员工人数’的会议记录的完整内容，分析分配给我部门的行动项目，并创建带有源注释参考的时间顺序时间表”

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

Related MCP server: Obsidian MCP Server

先决条件

在您的 Obsidian 库中安装Obsidian Local REST API插件
在 Obsidian 设置中配置并启用插件
记下 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，并禁用本地 Obsidian 实例常用的自签名证书的 SSL 证书验证。对于 HTTP 连接，请设置OBSIDIAN_API_URL="http://localhost:27123" 。

用法

运行 MCP 服务器：

obsidian-mcp

可用工具

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

search_vault - 具有灵活过滤器和完整内容检索的高级搜索：
- query - 跨注释内容的文本或正则表达式搜索（可选）
- query_type - 搜索类型：“text”（默认）或“regex”
- search_in_path - 将搜索限制在特定文件夹路径
- title_contains - 按注释标题中的文本过滤（字符串、数组或 JSON 字符串）
- title_match_mode - 如何匹配多个词：“any”（OR）或“all”（AND）
- tag - 按标签过滤（字符串、数组或 JSON 字符串 - 搜索前置内容和内联 #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强制对任何搜索进行完整内容检索
- 支持正则表达式模式进行复杂的文本匹配（或条件、不区分大小写的搜索等）
get_note_content - 通过路径检索特定笔记的完整内容和元数据
browse_vault_structure - 高效浏览保险库目录结构：
- path - 浏览目录（默认为保管库根目录）
- include_files - 布尔值以包含文件（默认值：False，仅为提高速度而包含文件夹）
- recursive -布尔值浏览所有嵌套目录

示例用例

基本搜索

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

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

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

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

查找具有所有标题术语（和逻辑）的注释：

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

高级多步骤工作流程

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

战略项目分析：

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

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

会议行动项目挖掘：

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

代理扫描内容中的行动项目、提取任务并创建按时间顺序排列的跟踪

研究差距分析：

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

代理识别知识差距并建议可以提供帮助的团队成员

保险库结构探索：

# Quick organizational overview
browse_vault_structure(recursive=True)

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

基于标签的知识图谱：

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

Obsidian MCP Server