使用说明

黑曜石MCP服务器

🎉 2.0版本发布！

v2.0的主要改进：

⚡ 搜索速度提高5倍 具有持久SQLite索引
🖼️ 图像支持 -查看和分析vault中的图像
🔍 强大的正则表达式搜索 -在笔记中找到复杂的模式
🗂️ 房产搜索 -按前台属性（状态、优先级等）查询
🚀 一个命令设置 -自动配置克劳德桌面 uvx --from obsidian-mcp obsidian-mcp-configure --vault-path /path/to/your/vault
🔄 直接文件系统访问 -无需插件，离线工作
📦 内存使用量减少90% -高效的流媒体架构

一个模型上下文协议（MCP）服务器，使克劳德等人工智能助手能够与您的黑曜石金库进行交互。该服务器通过直接文件系统访问提供了在黑曜石中读取、创建、搜索和管理笔记的工具，由于智能索引，其性能非常快。

特性

📖 读写笔记 -通过自动覆盖保护完全访问您的黑曜石保险库
🔍 闪电般的快速搜索 -通过持久索引按内容、标签、属性或修改日期立即查找笔记
🖼️ 图像分析 -查看和分析嵌入在笔记中或存储在vault中的图像
🔎 正则表达式功率搜索 -使用正则表达式查找代码模式、URL或复杂的文本结构
🗂️ 房产搜索 -通过带有运算符（=、>、<、contains、exists）的frontmatter属性查询注释
📁 浏览保险库 -按目录列出和浏览笔记和文件夹
🏷️ 标签管理 -添加、删除和组织标签（支持分层标签、frontmatter和内联标签）
🔗 链路管理 -查找反向链接，分析传出链接，并识别断开的链接
✏️ 智能重命名 -在整个保管库中使用自动链接更新重命名笔记
📊 注意见解 -获取字数统计和链接分析等统计数据
🎯 AI优化 -清晰的错误消息和智能默认值，以实现更好的AI交互
🔒 安全 -通过路径验证直接访问文件系统
⚡ 性能优化 -大型保管库的持久SQLite索引、并发操作和流式处理
🚀 批量操作 -创建文件夹层次结构并移动整个文件夹及其所有内容

先决条件

黑曜石 本地文件系统上的vault
Python 3.10+ 安装在您的系统上
Node.js （可选，用于运行MCP检查器）

安装

自动配置快速安装（Claude Desktop）

v2.0中的新功能！ 使用一个命令自动配置Claude Desktop：

# Install and configure in one step
uvx --from obsidian-mcp obsidian-mcp-configure --vault-path /path/to/your/vault

此命令将：

✅ 自动查找您的Claude Desktop配置
✅ 添加黑曜石MCP服务器
✅ 将旧的REST API配置迁移到v2.0
✅ 创建现有配置的备份
✅ 在macOS、Windows和Linux上工作

手动配置

找到你的黑曜石保险库：
- 在文件系统上找到黑曜石保管库的路径
- 例子： /Users/yourname/Documents/MyVault 或 C:\Users\YourName\Documents\MyVault
配置您的AI工具：
Claude Desktop

编辑您的Claude Desktop配置文件：
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- 窗户： %APPDATA%\Claude\claude_desktop_config.json
```
{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": ["obsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}
```
Cursor IDE

添加到光标设置中：
- 项目具体： .cursor/mcp.json 在您的项目目录中
- 全球的： ~/.cursor/mcp.json 在您的主目录中
```
{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": ["obsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}
```
然后：打开设置→ 光标设置→ 启用MCP
Windsurf IDE

编辑您的Windsurf配置文件：
- 地点： ~/.codeium/windsurf/mcp_config.json
```
{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": ["obsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}
```
然后：打开风帆设置→ 高级设置→ 级联→ 添加服务器→ 刷新
重新启动AI工具 加载新配置。

就是这样！服务器现在将在您的AI工具中可用，可以访问您的黑曜石保险库。

注：这使用 uvx 其在隔离环境中自动下载并运行服务器。大多数用户不需要安装其他任何东西。如果你没有 uv 安装后，您也可以使用 pipx install obsidian-mcp 并将命令更改为 "obsidian-mcp" 在配置中。

试试看

以下是一些入门提示示例：

“显示我本周修改的所有笔记”
“使用我的会议议程为今天创建一个新的每日笔记”
“搜索有关项目规划的所有注释”
“阅读我的想法/startup.md笔记”

开发安装

克隆存储库：

git clone https://github.com/natestrong/obsidian-mcp
cd obsidian-mcp

设置Python环境：

# Using pyenv (recommended)
pyenv virtualenv 3.12.9 obsidian-mcp
pyenv activate obsidian-mcp

# Or using venv
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

安装依赖项：
```
pip install -r requirements.txt
```

配置环境变量：

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"

运行服务器：
```
python -m obsidian_mcp.server
```

添加到Claude Desktop（用于开发）：

编辑您的Claude Desktop配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/python",
      "args": ["-m", "obsidian_mcp.server"],
      "cwd": "/path/to/obsidian-mcp",
      "env": {
        "PYTHONPATH": "/path/to/obsidian-mcp",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

项目结构

obsidian-mcp/
├── obsidian_mcp/
│   ├── server.py           # Main entry point with rich parameter schemas
│   ├── tools/              # Tool implementations
│   │   ├── note_management.py    # CRUD operations
│   │   ├── search_discovery.py   # Search and navigation
│   │   ├── organization.py       # Tags, moves, metadata
│   │   └── link_management.py    # Backlinks, outgoing links, broken links
│   ├── models/             # Pydantic models for validation
│   │   └── obsidian.py    # Note, SearchResult, VaultItem models
│   ├── utils/              # Shared utilities
│   │   ├── filesystem.py        # Direct filesystem access
│   │   ├── validators.py        # Path validation, sanitization
│   │   └── validation.py        # Comprehensive parameter validation
│   └── constants.py       # Constants and error messages
├── tests/
│   ├── run_tests.py       # Test runner
│   └── test_filesystem_integration.py # Integration tests
├── docs/                  # Additional documentation
├── requirements.txt       # Python dependencies
├── CLAUDE.md             # Instructions for Claude Code
└── README.md

可用工具

笔记管理

`read_note`

阅读特定笔记的内容和元数据。

参数：

path：注释路径（例如，“Daily/2024-01-15.md”）

退货：

{
  "path": "Daily/2024-01-15.md",
  "content": "# Daily Note\n\nContent here...",
  "metadata": {
    "tags": ["daily", "journal"],
    "aliases": [],
    "frontmatter": {}
  }
}

`create_note`

创建新笔记或更新现有笔记。

参数：

path：应创建注释的路径
content：注释的Markdown内容（考虑为组织添加标签）
overwrite （默认值： false)：是否覆盖现有笔记

最佳实践：

在创建笔记时添加相关标签以保持组织
使用 list_tags 查看现有标签并保持一致性
标签可以作为内联标签添加(#tag)或在正面

`update_note`

更新现有注释的内容。

⚠️ 重要：默认情况下，此工具会替换整个笔记内容。如果需要保留现有内容，请务必先阅读注释。

参数：

path：要更新的注释的路径
content：新的降价内容（除非使用append，否则替换现有内容）
create_if_not_exists （默认值： false)：如果不存在则创建
merge_strategy （默认值： "replace")：如何处理内容
- "replace"：覆盖整个笔记内容（默认）
- "append"：将新内容添加到现有内容的末尾

安全更新模式：

始终先阅读以保留内容
根据需要修改内容
更新完整的新内容
或者使用追加模式将内容添加到末尾

`edit_note_section`

编辑注释中由标记标题标识的特定部分。

参数：

path：要编辑的注释的路径
section_identifier：标识该部分的Markdown标题（例如，“##任务”、“###状态”）
content：要插入、替换或附加的内容
operation （默认值： "insert_after")：如何编辑该部分
- "insert_after"：在章节标题后添加内容
- "insert_before"：在章节标题前添加内容
- "replace"：替换整个章节，包括标题
- "append_to_section"：在本节末尾添加内容
create_if_missing （默认值： false)：如果不存在，则创建节

示例用法：

# Add tasks to a specific section
await edit_note_section(
    "Daily/2024-01-15.md",
    "## Tasks",
    "- [ ] Review PR\n- [ ] Update docs",
    operation="append_to_section"
)

# Update a status section
await edit_note_section(
    "Projects/Website.md",
    "### Current Status",
    "### Current Status\n\nPhase 2 completed!",
    operation="replace"
)

使用案例：

在不重写整个笔记的情况下将项目添加到任务列表中
更新项目注释中的状态部分
按章节逐步建立笔记
在精确的位置插入内容

`delete_note`

从vault中删除注释。

参数：

path：要删除的注释的路径

搜索和发现

`search_notes`

搜索包含特定文本或标签的笔记。

参数：

query：搜索查询（支持黑曜石搜索语法）
context_length （默认值： 100)：匹配项周围显示的字符数
max_results （默认值： 50)：返回的最大结果数（1-500）

搜索语法：

文本搜索： "machine learning"
标签搜索： tag:project 或 tag:#project
- 分层标签： tag:project/web （完全匹配）
- 父搜索： tag:project （查找项目、项目/网络、项目/移动）
- 儿童搜索： tag:web （查找项目/网页、设计/网页）
路径搜索： path:Daily/
房产搜索： property:status:active 或 property:priority:>2
组合： tag:urgent TODO

退货：

{
  "results": [...],        // Array of matched notes
  "total_count": 150,      // Total matches found
  "limit": 50,             // max_results used
  "truncated": true        // More results available
}

房产搜索示例：

property:status:active -查找状态为“活动”的注释
property:priority:>2 -查找优先级>2的注释
property:author:*john* -查找作者包含“john”的注释
property:deadline:* -查找具有截止日期属性的笔记
property:rating:>=4 -查找评分>=4的笔记
property:tags:project -在标签数组中查找带有“project”的笔记
property:due_date:<2024-12-31 -查找到期日期在2024年12月31日之前的笔记

`search_by_date`

按创建或修改日期搜索笔记。

参数：

date_type （默认值： "modified")：“创建”或“修改”
days_ago （默认值： 7)：回顾的天数
operator （默认值： "within")：“在”（最近N天）或“恰好”（恰好N天前）

退货：

{
  "query": "Notes modified within last 7 days",
  "count": 15,
  "results": [
    {
      "path": "Daily/2024-01-15.md",
      "date": "2024-01-15T10:30:00",
      "days_ago": 1
    }
  ]
}

示例用法：

“显示今天修改的所有笔记”→ search_by_date("modified", 0, "within")
“显示本周修改的所有笔记”→ search_by_date("modified", 7, "within")
“查找过去30天内创建的笔记”→ search_by_date("created", 30, "within")
“两天前修改了哪些笔记？”→ search_by_date("modified", 2, "exactly")

`search_by_regex`

使用正则表达式搜索笔记以进行高级模式匹配。

参数：

pattern：要搜索的正则表达式模式
flags （可选）：正则表达式标志列表（“ignorecase”、“multiline”、“dotall”）
context_length （默认值： 100)：在比赛中显示的角色
max_results （默认值： 50)：最大结果数

何时使用：

查找代码模式（函数、导入、语法）
搜索结构化数据
简单搜索无法处理的复杂文本模式

常见模式：

# Find Python imports
"(import|from)\\s+fastmcp"

# Find function definitions
"def\\s+\\w+\\s*\\([^)]*\\):"

# Find TODO comments
"(TODO|FIXME)\\s*:?\\s*(.+)"

# Find URLs
"https?://[^\\s)>]+"

# Find code blocks
"```python([^`]+)```"

退货：

{
  "pattern": "def\\s+search\\w*",
  "count": 2,
  "results": [
    {
      "path": "code/utils.py",
      "match_count": 3,
      "matches": [
        {
          "match": "def search_notes",
          "line": 42,
          "context": "...async def search_notes(query)..."
        }
      ]
    }
  ]
}

`search_by_property`

使用高级过滤功能按笔记的frontmatter属性值搜索笔记。

参数：

property_name：要搜索的房产名称
value （可选）：要比较的值
operator （默认值： "=")：比较运算符
context_length （默认值： 100)：要包括的注释内容的字符

操作员：

"="：完全匹配（不区分大小写）
"!="：不相等
">", "<", ">=", "<="：数字/日期比较
"contains"：属性值包含搜索值
"exists"：属性存在（忽略值参数）

支持的属性类型：

文本/字符串：标准文本比较
数字：操作员的自动数字比较
日期：具有智能日期解析的ISO格式（YYYY-MM-DD）
数组/列表：在数组项内搜索，比较使用数组长度
遗留财产：自动处理 tag→tags, alias→aliases 迁移

退货：

{
  "property": "status",
  "operator": "=",
  "value": "active",
  "count": 5,
  "results": [
    {
      "path": "Projects/Website.md",
      "matches": ["status = active"],
      "context": "status: active\n\n# Website Redesign Project...",
      "property_value": "active"
    }
  ]
}

示例用法：

查找所有活动项目： search_by_property("status", "active")
查找高优先级项目： search_by_property("priority", "2", ">")
查找有截止日期的笔记： search_by_property("deadline", operator="exists")
查找部分作者的注释： search_by_property("author", "john", "contains")

`list_notes`

使用可选的递归遍历列出vault中的注释。

参数：

directory （可选）：要列出的特定目录（例如，“Daily”、“Projects”）
recursive （默认值： true)：递归列出所有笔记

退货：

{
  "directory": "Daily",
  "recursive": true,
  "count": 365,
  "notes": [
    {"path": "Daily/2024-01-01.md", "name": "2024-01-01.md"},
    {"path": "Daily/2024-01-02.md", "name": "2024-01-02.md"}
  ]
}

`list_folders`

使用可选的递归遍历列出vault中的文件夹。

参数：

directory （可选）：要列出的特定目录
recursive （默认值： true)：包括所有嵌套的子文件夹

退货：

{
  "directory": "Projects",
  "recursive": true,
  "count": 12,
  "folders": [
    {"path": "Projects/Active", "name": "Active"},
    {"path": "Projects/Archive", "name": "Archive"},
    {"path": "Projects/Ideas", "name": "Ideas"}
  ]
}

组织

`create_folder`

在vault中创建一个新文件夹，包括路径中的所有父文件夹。

参数：

folder_path：要创建的文件夹的路径（例如，“研究/学习/2024”）
create_placeholder （默认值： true)：是否创建占位符文件

退货：

{
  "folder": "Research/Studies/2024",
  "created": true,
  "placeholder_file": "Research/Studies/2024/.gitkeep",
  "folders_created": ["Research", "Research/Studies", "Research/Studies/2024"]
}

注：此工具将创建所有必要的父文件夹。例如，如果“研究”存在，但“研究”不存在，它将创建“研究”和“2024”。

`move_note`

将注释移动到新位置，可以选择使用新名称。

参数：

source_path：注释的当前路径
destination_path：注释的新路径（可以包括新文件名）
update_links （默认值： true)：如果文件名更改，则更新链接

特征：

可以移动到其他文件夹： move_note("Inbox/Note.md", "Archive/Note.md")
可以移动和重命名： move_note("Inbox/Old.md", "Archive/New.md")
自动检测文件名是否更改并更新所有wiki样式的链接
简单的文件夹移动不需要更新链接（黑曜石链接按名称工作）
更新时保留链接别名

退货：

{
  "success": true,
  "source": "Inbox/Quick Note.md",
  "destination": "Projects/Project Plan.md",
  "renamed": true,
  "details": {
    "links_updated": 5,
    "notes_updated": 3
  }
}

`rename_note`

重命名注释并自动更新整个vault中对它的所有引用。

参数：

old_path：注释的当前路径
new_path：注释的新路径（必须在同一目录中）
update_links （默认值： true)：自动更新所有wiki样式的链接

退货：

{
  "success": true,
  "old_path": "Projects/Old Name.md",
  "new_path": "Projects/New Name.md",
  "operation": "renamed",
  "details": {
    "links_updated": 12,
    "notes_updated": 8,
    "link_update_details": [
      {"note": "Daily/2024-01-15.md", "updates": 2},
      {"note": "Ideas/Related.md", "updates": 1}
    ]
  }
}

特征：

自动查找并更新所有 [[wiki-style links]] 到重命名的注释
保留链接别名（例如。， [[Old Name|Display Text]] → [[New Name|Display Text]])
处理各种链接格式： [[Note]], [[Note.md]], [[Note|Alias]]
显示哪些笔记已更新以提高透明度
只能在同一目录中重命名（使用 move_note 更改目录）

`move_folder`

将整个文件夹及其所有内容移动到新位置。

参数：

source_folder：当前文件夹路径（例如，“项目/旧”）
destination_folder：新文件夹路径（例如“存档/项目/旧”）
update_links （默认值： true)：更新其他说明中的链接（未来增强）

退货：

{
  "source": "Projects/Completed",
  "destination": "Archive/2024/Projects",
  "moved": true,
  "notes_moved": 15,
  "folders_moved": 3,
  "links_updated": 0
}

`add_tags`

在笔记的封面添加标签。

参数：

path：注释路径
tags：要添加的标签列表（不带#前缀）

支持分层标记：

简单标签： ["project", "urgent"]
分层标签： ["project/web", "work/meetings/standup"]
混合的： ["urgent", "project/mobile", "status/active"]

`update_tags`

更新笔记上的标签-替换所有标签或与现有标签合并。

参数：

path：注释路径
tags：要设置的新标记（不带#前缀）
merge （默认值： false)：如果为true，则添加到现有标签中。如果为false，则替换所有标签

非常适合AI工作流程：

User: "Tell me what this note is about and add appropriate tags"
AI: [reads note] "This note is about machine learning research..."
AI: [uses update_tags to set tags: ["ai", "research", "neural-networks"]]

`remove_tags`

从笔记的封面删除标签。

参数：

path：注释路径
tags：要删除的标签列表

`batch_update_properties`

跨多个笔记批量更新属性。

参数：

search_criteria：如何查找笔记-必须包括以下内容之一：
- query：搜索查询字符串（例如，“标签：项目状态：活动”）
- folder：文件夹路径（可选） recursive 旗帜
- files：文件路径的显式列表
property_updates （可选）：要在frontmatter中添加/更新的属性
properties_to_remove （可选）：要删除的属性名称列表
add_tags （可选）：要添加的标签（附加）
remove_tags （可选）：要删除的标签
remove_inline_tags （默认值： false)：同时从笔记正文中删除标签

示例：

# Archive completed projects
{
  "search_criteria": {"query": "tag:project status:completed"},
  "property_updates": {"archived": true, "year": 2024},
  "add_tags": ["archived"]
}

# Remove draft tags everywhere
{
  "search_criteria": {"query": "tag:draft"},
  "remove_tags": ["draft"],
  "remove_inline_tags": true
}

退货：

{
  "total_notes": 10,
  "updated": 8,
  "failed": 2,
  "details": [...],
  "errors": [...]
}

`get_note_info`

获取有关笔记的元数据和统计信息，而无需检索其全部内容。

参数：

path：注释路径

退货：

{
  "path": "Projects/AI Research.md",
  "exists": true,
  "metadata": {
    "tags": ["ai", "research"],
    "aliases": [],
    "frontmatter": {}
  },
  "stats": {
    "size_bytes": 4523,
    "word_count": 823,
    "link_count": 12
  }
}

图像管理

`read_image`

查看vault中的图像。图像会自动调整为最大宽度800px，以便在Claude Desktop中获得最佳显示效果。

参数：

path：图像文件的路径（例如，“附件/screscent.png”）

退货：

可以在Claude Desktop中直接查看的调整大小的图像对象

支持的格式：

PNG、JPG/JPEG、GIF、BMP、WebP

`view_note_images`

提取并查看笔记中嵌入的所有图像。

参数：

path：包含图像的笔记的路径

退货：

{
  "note_path": "Projects/Design Mockups.md",
  "image_count": 3,
  "images": [
    {
      "path": "Attachments/mockup1.png",
      "alt_text": "Homepage design",
      "image": "<FastMCP Image object>"
    }
  ]
}

使用案例：

分析笔记中的屏幕截图和图表
审查设计模型和视觉文档
提取视觉信息进行人工智能分析

`list_tags`

列出整个保管库中使用的所有唯一标签及其使用统计信息。

参数：

include_counts （默认值： true)：包括每个标签的使用次数
sort_by （默认值： "name")：按“名称”或“计数”排序
include_files （默认值： false)：包括包含每个标记的文件路径列表

退货：

{
  "items": [
    {
      "name": "project", 
      "count": 42,
      "files": ["Projects/Web.md", "Projects/Mobile.md"]  // if include_files=true
    },
    {"name": "meeting", "count": 38},
    {"name": "idea", "count": 15}
  ],
  "total": 25,
  "scope": {"include_counts": true, "sort_by": "name", "include_files": false}
}

注：分层标签作为单独的条目列出，显示父路径和完整路径。

性能说明：

适用于小型金库（<1000张纸币）
大型保险库可能需要几秒钟
使用并发批处理进行优化

链路管理

⚡ 性能说明： 链接管理工具在v1.1.5中进行了大量优化：

快84倍 链接有效性检查
快96倍 断链检测
速度提高2倍 反向链接搜索
包括自动缓存和批处理

`find_orphaned_notes`

根据各种标准查找可能需要组织或清理的笔记。

参数：

orphan_type （默认值： "no_backlinks")：识别孤立笔记的标准
- "no_backlinks"：没有传入链接的笔记（最常见）
- "no_links"：没有传入或传出链接的笔记
- "no_tags"：没有任何标签的注释
- "no_metadata"：具有最小/无正面属性的注释
- "isolated"：没有链接和标签的笔记
exclude_folders （可选）：要排除的文件夹列表（默认值：[“模板”、“存档”、“每日”]）
min_age_days （可选）：仅包含超过此天数的笔记

退货：

{
  "count": 23,
  "orphaned_notes": [
    {
      "path": "Random Thoughts/Old Idea.md",
      "reason": "No incoming links",
      "modified": "2023-06-15T10:30:00Z",
      "size": 245,
      "word_count": 42
    }
  ],
  "stats": {
    "total_notes_scanned": 500,
    "excluded_folders": ["Templates", "Archive", "Daily"],
    "orphan_type": "no_backlinks"
  }
}

使用案例：

定期维护和清理保险库
查找遗忘或断开连接的笔记
识别需要更好组织的笔记
为保险库重组做准备

`get_backlinks`

查找链接到特定笔记的所有笔记。

参数：

path：查找反向链接的注释路径
include_context （默认值： true)：是否在链接周围包含文本上下文
context_length （默认值： 100)：要包含的上下文字符数

退货：

{
  "target_note": "Projects/AI Research.md",
  "backlink_count": 5,
  "backlinks": [
    {
      "source_path": "Daily/2024-01-15.md",
      "link_text": "AI Research",
      "link_type": "wiki",
      "context": "...working on the [[AI Research]] project today..."
    }
  ]
}

使用案例：

了解哪些笔记引用了一个概念或主题
发现笔记之间的关系
构建音符连接的心理图

`get_outgoing_links`

列出特定注释中的所有链接。

参数：

path：从中提取链接的注释路径
check_validity （默认值： false)：是否检查是否存在链接的笔记

退货：

{
  "source_note": "Projects/Overview.md",
  "link_count": 8,
  "links": [
    {
      "path": "Projects/AI Research.md",
      "display_text": "AI Research",
      "type": "wiki",
      "exists": true
    }
  ]
}

使用案例：

理解注释所指的内容
移动/删除前检查笔记依赖关系
探索索引或中心注释的结构

`find_broken_links`

查找vault、特定目录或单个注释中的所有断开链接。

参数：

directory （可选）：要检查的特定目录（默认为整个vault）
single_note （可选）：仅检查此特定注释中的断开链接

退货：

{
  "directory": "/",
  "broken_link_count": 3,
  "affected_notes": 2,
  "broken_links": [
    {
      "source_path": "Projects/Overview.md",
      "broken_link": "Projects/Old Name.md",
      "link_text": "Old Project",
      "link_type": "wiki"
    }
  ]
}

使用案例：

重命名或删除笔记后
定期保管库维护
重新组织文件夹结构之前

测试

运行测试

# Run all tests
python tests/run_tests.py

# Or with pytest directly
pytest tests/

测试创建用于隔离的临时保管库，不需要正在运行的黑曜石实例。

MCP检验员测试

设置vault路径：

export OBSIDIAN_VAULT_PATH="/path/to/your/vault"

运行MCP检查器：

npx @modelcontextprotocol/inspector python -m obsidian_mcp.server

打开检查器UI 在 http://localhost:5173
测试工具 与您的实际保险库交互

与Claude Desktop集成

有关开发安装，请参阅开发安装上面的部分。

增强的错误处理

服务器提供详细的、可操作的错误消息，以帮助人工智能系统从错误中恢复：

错误消息示例

无效路径:

Invalid note path: '../../../etc/passwd'. 
Valid paths must: 1) End with .md or .markdown, 2) Use forward slashes (e.g., 'folder/note.md'), 
3) Not contain '..' or start with '/', 4) Not exceed 255 characters. 
Example: 'Daily/2024-01-15.md' or 'Projects/My Project.md'

空搜索查询:

Search query cannot be empty. 
Valid queries: 1) Keywords: 'machine learning', 
2) Tags: 'tag:#project', 3) Paths: 'path:Daily/', 
4) Combined: 'tag:#urgent TODO'

日期参数无效:

Invalid date_type: 'invalid'. 
Must be either 'created' or 'modified'. 
Use 'created' to find notes by creation date, 'modified' for last edit date

故障排除

“未找到保险库”错误

确保OBSIDIAN_VAULT_PATH环境变量设置正确
验证路径是否指向现有的Obsidian vault目录
检查您是否具有vault目录的读/写权限

标签未显示

确保标签格式正确（有或没有#前缀）
frontmatter中的标签应采用YAML数组格式： tags: [tag1, tag2]
内联标签应使用#前缀： #project #urgent
代码块内的标签会自动排除

“文件太大”错误

服务器对笔记文件的限制为10MB，对图像的限制为50MB
这可以防止非常大的文件出现内存问题
考虑将大额纸币拆分为小额纸币

“找不到模块”错误

确保您的虚拟环境已激活
从项目根目录运行： python -m obsidian_mcp.server
验证是否安装了所有依赖项： pip install -r requirements.txt

列出注释时结果为空

使用时指定目录 list_notes （例如，“每日”、“项目”）
根目录列表需要递归实现
检查笔记是否在子目录中

标签未更新

确保笔记有用于frontmatter标签的YAML frontmatter部分
前台必须包括 tags: 字段（即使为空）
服务器现在可以正确读取frontmatter标签和内联标签

人工智能助理的最佳实践

防止数据丢失

更新前务必阅读：The update_note 工具默认替换内容
使用附加模式进行添加：添加到现有笔记时，请使用 merge_strategy="append"
检查钞票是否存在：使用 read_note 在修改之前验证注释是否存在
明确覆盖：仅使用 overwrite=true 故意替换内容时

安全考虑

保险库路径访问 -服务器仅访问指定的vault目录
服务器验证所有路径以防止目录遍历攻击
文件操作仅限于vault目录
拒绝大文件以防止内存耗尽
路径验证阻止访问系统文件

发展

代码的风格

使用FastMCP框架实现MCP
用于类型安全和验证的Pydantic模型
具有独立关注点的模块化架构
全面的错误处理和用户友好的消息

添加新工具

在相应的模块中创建工具功能 src/tools/
如果需要，在中添加Pydantic模型 src/models/
在中注册该工具 src/server.py 随着 @mcp.tool() 装饰器
包含全面的文档字符串
在中添加测试 tests/
部署前使用MCP检查器进行测试

更新日志

v2.1.6（2025-01-30）

🔍 查找孤立笔记 新 find_orphaned_notes 保险库综合维护工具
- 多个孤立标准：无反向链接、无链接、无标签、无元数据或孤立注释
- 可配置的文件夹排除和年龄过滤
- 返回每个孤立笔记的详细统计信息，包括大小和字数
- 帮助识别需要整理的遗忘或断开连接的笔记
🐛 错误修复:
- 修复了多个工具中标记参数的JSON字符串解析问题
- 修复了中的各种错误 find_orphaned_notes 实施

v2.1.5（2025-01-30）

🔍 新的find_orphaned_notes工具 -查找需要整理的笔记
- 多个标准：无反向链接、无链接、无标签、无元数据或隔离
- 智能默认值不包括模板、存档和每日文件夹
- 可选的年龄筛选，以排除最近正在进行的工作笔记
- 返回每个孤立笔记的路径、原因和元数据

v2.1.4（2025-01-30）

🔍 增强的默认搜索 -搜索现在自动包括文件名和内容匹配
- 由于直观的“按名称查找注释”行为，文件名匹配的排名更高
- 不再需要使用 path: 常用搜索的前缀
- 添加 match_type 用于区分文件名与内容匹配的字段
🐛 固定报价验证 -文件名中带引号的注释现在可以正常工作了

v2.1.3（2025-01-30）

🏷️ 增强列表标签 -已添加 include_files 获取包含每个标记的所有文件的选项
🔧 固定更新标签 -正确处理项目符号列表YAML格式，而不会创建格式错误的frontmatter
🚀 批量更新属性 新 batch_update_properties 批量元数据操作工具
- 在多个笔记中更新任何frontmatter属性
- 添加/删除标签，可从注释正文中删除内联标签
- 按查询、文件夹或显式文件列表搜索
- 正确保存YAML结构
🧹 代码清理 -从代码库中删除了不推荐使用的OBSIDIAN_RESST_API_KEY引用
📝 更好的错误消息 -遵循MCP最佳实践，获得更多可操作的反馈

v2.0.3（2025年1月24日）

✏️ 基于章节的编辑 新 edit_note_section 用于精确插入和更新内容的工具
🎯 四种编辑操作 -在标题前后插入、替换章节或附加到章节末尾
📍 智能区段检测 -不区分大小写的标记标题与层次结构支持相匹配
🔧 创建缺失的部分 -如果不存在，可以选择创建部分
📝 保留笔记结构 -编辑特定部分而不重写整个笔记

v2.0.2（2025-01-24）

🎯 简化的架构 -删除了内存索引，SQLite现在是唯一的搜索方法
🔍 搜索透明度 -在搜索结果中添加元数据（总计、截断、限制）
⚙️ 可配置的搜索限制 -暴露的max_results参数（1-500，默认值50）
🧹 减少工具杂乱 -删除了不必要的索引管理工具
📝 推理友好型改进 -通过适当的字段注释和全面的文档字符串增强了所有工具
🚀 更好的AI推理 -在所有工具中添加了“何时使用”和“何时不使用”部分
⚡ 业绩说明 -为昂贵的操作添加了明确的性能指导
🔧 更干净的代码库 -删除了约500行内存索引代码，减轻了维护负担

v2.0.0（2025-01-24）

🚀 全面架构检修 -从REST API迁移到直接文件系统访问
⚡ 搜索速度提高5倍 具有在会话之间生存的持久SQLite索引
🖼️ 图像支持 -通过自动调整大小查看和分析vault中的图像
🔍 正则表达式功率搜索 -使用优化的流媒体查找复杂模式
🗂️ 房产搜索 -使用高级运算符按frontmatter属性查询笔记
🎯 一个命令设置 -自动配置克劳德桌面 uvx --from obsidian-mcp obsidian-mcp-configure
📦 内存使用量减少90% -高效的流媒体架构
🔄 无需插件 -离线工作，无需运行Obsidian
✨ 增量索引 -仅重新索引已更改的文件
🔧 迁移支持 -自动检测并迁移旧的REST API配置
🏷️ 增强的分层标签支持 -完全支持Obsidian的嵌套标签系统
- 搜索父标签以找到所有子标签（例如。， tag:project 发现 project/web)
- 在任何层次结构中搜索子标签（例如。， tag:web 发现 project/web, design/web)
- 精确的分层匹配（例如。， tag:project/web)
🔍 改进了元数据处理 -更好地与黑曜石的房地产系统保持一致
- 自动迁移遗留属性(tag→tags, alias→aliases)
- 数组/列表属性搜索（在数组中查找项目）
- 与ISO格式支持的日期属性比较
- 数组长度的数值比较
📝 AI友好的工具定义 -更新了所有工具描述，以便更好地理解LLM
- 为所有与标签相关的工具添加了分层标签示例
- 增强的房产搜索文档
- 遵循MCP最佳实践的更清晰的参数描述

v1.1.8（2025-01-15）

🔧 修复了阻止PyPI包运行的FastMCP兼容性问题
📦 更新到FastMCP 2.8.1以获得更好的稳定性
🐛 修复Pydantic V2弃用警告（迁移到@field_validator）
✨ 将FastMCP初始化更改为使用“指令”参数
🚀 改进了与uvx和pipx安装方法的兼容性

v1.1.7（2025-01-10）

🔄 已将默认API终结点更改为HTTP(http://127.0.0.1:27123)更容易设置
📝 更新文档以反映HTTP为默认值，HTTPS为可选值
🔧 添加了关于URL中自动尾随斜线处理的说明
✨ 通过零配置设置改善了首次用户体验

v1.1.6（2025-01-10）

🐛 修复了创建或更新大型笔记时的超时错误
⚡ 添加了优雅的超时处理，以提高大内容的可靠性
🔧 改进了错误报告，以防止成功操作时出现错误

v1.1.5（2025-01-09）

⚡ 链路管理的大规模性能优化：
- 链接有效性检查速度提高84倍
- 断链检测速度提高96倍
- 反向链接搜索速度提高2倍
- 添加了自动缓存和批处理
🔧 优化了大型保管库的并发操作
📝 增强了性能考虑的文档

v1.1.4（2025年1月9日）

🔗 添加了用于全面vault分析的链接管理工具：
- get_backlinks -查找链接到特定笔记的所有笔记
- get_outgoing_links -列出带有有效性检查的笔记中的所有链接
- find_broken_links -识别损坏的链接以进行保管库维护
🔧 修复了支持HTTPS（默认）和HTTP端点的URL构造
📝 增强的链接解析，可处理wiki风格和markdown链接
⚡ 优化反向链接搜索以处理各种路径格式

v1.1.3（2025年1月9日）

🐛 修复了搜索_by_date以正确查找今天修改的笔记的问题（days_ago=0）
✨ 添加了list_folders工具，用于探索vault文件夹结构
✨ 添加了创建完整文件夹层次结构的create_folder工具
✨ 添加了用于批量文件夹操作的move_folder工具
✨ 添加了用于AI驱动标签管理的update_tags工具
🐛 修复了标签读取，以正确处理frontmatter和内联标签
✨ 添加了list_tags工具，用于发现具有使用统计信息的现有标签
⚡ 通过并发批处理优化大型保险库的性能
📝 遵循MCP最佳实践改进文档和错误消息
🎯 增强create_note以鼓励标签使用，从而更好地组织

v1.1.2（2025年1月9日）

修复了PyPI包文档

v1.1.1（2025-01-06）

PyPI初始版本

发布（面向维护人员）

要将新版本发布到PyPI，请执行以下操作：

# 1. Update version in pyproject.toml
# 2. Clean old builds
rm -rf dist/ build/ *.egg-info/

# 3. Build the package
python -m build

# 4. Check the package
twine check dist/*

# 5. Upload to PyPI
twine upload dist/* -u __token__ -p $PYPI_API_KEY

# 6. Create and push git tag
git tag -a v2.0.2 -m "Release version 2.0.2"
git push origin v2.0.2

然后，用户可以安装并运行：

# Using uvx (recommended - no installation needed)
uvx obsidian-mcp

# Or install globally with pipx
pipx install obsidian-mcp
obsidian-mcp

# Or with pip
pip install obsidian-mcp
obsidian-mcp

配置

性能和索引

服务器现在包括 持久搜索索引 使用SQLite显著提高性能：

主要特点：

即时启动 -无需在每次服务器启动时重建索引
增量更新 -仅重新索引已更改的文件
搜索速度提高60倍 -SQLite查询比扫描所有文件快得多
降低内存使用率 -文件是按需加载的，而不是一次性加载的

配置选项：

设置这些环境变量以自定义行为：

# Set logging level (default: INFO, options: DEBUG, INFO, WARNING, ERROR)
export OBSIDIAN_LOG_LEVEL=DEBUG

搜索索引存储在您的保管库中 .obsidian/mcp-search-index.db.

业绩说明

搜索索引 -使用持久索引，只有更改的文件才会重新索引
并行操作 -文件操作使用异步I/O以获得更好的性能
大型金库 -增量索引使大型金库（10000+张纸币）可用
图像处理 -图像会自动调整大小以防止内存问题

从REST API版本迁移

如果您使用的是需要本地REST API插件的早期版本：

您不再需要Obsidian本地REST API插件 -此服务器现在使用直接文件系统访问
替换 OBSIDIAN_REST_API_KEY 随着 OBSIDIAN_VAULT_PATH 在您的配置中
删除任何 OBSIDIAN_API_URL 设置
新版本明显更快、更可靠
所有功能均可脱机工作，无需运行Obsidian

贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-tool)
为新功能编写测试
确保所有测试通过
提交您的更改(git commit -m 'Add amazing tool')
推到分支(git push origin feature/amazing-tool)
打开拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

Anthropic 用于创建模型上下文协议
黑曜石令人惊叹的笔记应用程序团队
科丁顿熊用于原始本地REST API插件（不再需要）
dsp蚂蚁适用于FastMCP框架

使用说明

黑曜石MCP服务器

🎉 2.0版本发布！

特性

先决条件

安装

自动配置快速安装（Claude Desktop）

手动配置

试试看

开发安装

项目结构

可用工具

笔记管理

read_note

create_note

update_note

edit_note_section

delete_note

搜索和发现

search_notes

search_by_date

search_by_regex

search_by_property

list_notes

list_folders

组织

create_folder

move_note

rename_note

move_folder

add_tags

update_tags

remove_tags

batch_update_properties

get_note_info

图像管理

read_image

view_note_images

list_tags

链路管理

find_orphaned_notes

get_backlinks

get_outgoing_links

find_broken_links

测试

运行测试

MCP检验员测试

与Claude Desktop集成

增强的错误处理

错误消息示例

故障排除

“未找到保险库”错误

标签未显示

“文件太大”错误

“找不到模块”错误

列出注释时结果为空

标签未更新

人工智能助理的最佳实践

防止数据丢失

推荐工作流程

安全考虑

发展

代码的风格

添加新工具

更新日志

v2.1.6（2025-01-30）

v2.1.5（2025-01-30）

v2.1.4（2025-01-30）

v2.1.3（2025-01-30）

v2.0.3（2025年1月24日）

v2.0.2（2025-01-24）

v2.0.0（2025-01-24）

v1.1.8（2025-01-15）

v1.1.7（2025-01-10）

v1.1.6（2025-01-10）

v1.1.5（2025-01-09）

v1.1.4（2025年1月9日）

v1.1.3（2025年1月9日）

v1.1.2（2025年1月9日）

v1.1.1（2025-01-06）

`read_note`

`create_note`

`update_note`

`edit_note_section`

`delete_note`

`search_notes`

`search_by_date`

`search_by_regex`

`search_by_property`

`list_notes`

`list_folders`

`create_folder`

`move_note`

`rename_note`

`move_folder`

`add_tags`

`update_tags`

`remove_tags`

`batch_update_properties`

`get_note_info`

`read_image`

`view_note_images`

`list_tags`

`find_orphaned_notes`

`get_backlinks`

`get_outgoing_links`

`find_broken_links`