Obsidian MCP

🚀 Obsidian MCP 服务器

Obsidian MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它能让像 Claude 这样的 AI 助手与你的 Obsidian 知识库进行交互。该服务器借助 Local REST API 插件，提供了读取、创建、搜索和管理 Obsidian 笔记的工具。

🚀 快速开始

快速安装

1. 安装并配置 Obsidian：

   • 在 Obsidian 中安装 Local REST API 插件。
   • 在“设置”>“社区插件”中启用该插件。
   • 进入“设置”>“Local REST API”。
   • 复制你的 API 密钥（在步骤 2 中会用到）。

2. 配置你的 AI 工具：

   Claude Desktop

   编辑你的 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   Cursor IDE

   在你的 Cursor 设置中添加以下内容：

   • 项目特定设置：项目目录下的 .cursor/mcp.json
   • 全局设置：主目录下的 ~/.cursor/mcp.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   然后：打开“设置”→“Cursor 设置”→启用 MCP。

   Windsurf IDE

   编辑你的 Windsurf 配置文件：

   • 位置：~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   然后：打开 Windsurf 设置→高级设置→级联→添加服务器→刷新。

   将 your-api-key-here 替换为你从 Obsidian 复制的 API 密钥。

   ⚠️ 重要提示

   如果你使用 HTTPS 或自定义端口，请在 env 部分添加 "OBSIDIAN_API_URL": "https://localhost:27124"。详情请参阅 高级配置。

3. 重启你的 AI 工具 以加载新配置。

大功告成！现在你的 AI 工具可以访问你的 Obsidian 知识库了。

💡 使用建议

此安装方式使用了 uvx，它会自动下载并在隔离环境中运行服务器。大多数用户无需再安装其他东西。如果你没有安装 uv，也可以使用 pipx install obsidian-mcp，并在配置中将命令改为 "obsidian-mcp"。

立即试用

以下是一些示例提示，助你快速上手：

• "显示我本周修改过的所有笔记"
• "为今天创建一篇包含会议议程的日常笔记"
• "搜索所有关于项目规划的笔记"
• "读取我的 Ideas/startup.md 笔记"

开发安装

1. 克隆仓库：

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

2. 设置 Python 环境：

# 使用 pyenv（推荐）
pyenv virtualenv 3.12.9 obsidian-mcp
pyenv activate obsidian-mcp

# 或者使用 venv
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

3. 安装依赖项：

pip install -r requirements.txt

4. 设置 Obsidian Local REST API：
   • 在 Obsidian 中安装 Local REST API 插件。
   • 在 Obsidian 设置中启用该插件。
   • 从插件设置中复制 API 密钥。
   • 记录端口号（默认：HTTP 为 27123，HTTPS 为 27124）。
5. 配置环境变量：

export OBSIDIAN_REST_API_KEY="your-api-key-here"
# export OBSIDIAN_API_URL="https://localhost:27124"  # 可选：仅在使用 HTTPS 时设置

6. 添加到 Claude Desktop（用于开发）： 编辑你的 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/obsidian-mcp",
      "env": {
        "PYTHONPATH": "/path/to/obsidian-mcp",
        "OBSIDIAN_REST_API_KEY": "your-api-key-here"
      }
    }
  }
}

✨ 主要特性

• 📖 读写笔记 - 可完全访问你的 Obsidian 知识库，并具备自动覆盖保护功能。
• 🔍 智能搜索 - 可根据内容、标签或修改日期查找笔记。
• 📁 浏览知识库 - 按目录列出并导航你的笔记和文件夹。
• 🏷️ 标签管理 - 添加、删除和组织标签（支持前置元数据和内联标签）。
• 🔗 链接管理 - 查找反向链接、分析出站链接并识别断链。
• 📊 笔记洞察 - 获取诸如字数统计和链接分析等统计信息。
• 🎯 AI 优化 - 清晰的错误消息和智能默认设置，以实现更好的 AI 交互。
• 🔒 安全可靠 - 通过 API 密钥认证，仅支持本地连接。
• ⚡ 性能优化 - 支持并发操作和批量处理，适用于大型知识库。
• 🚀 批量操作 - 创建文件夹层次结构并移动整个文件夹及其所有内容。

📦 安装指南

快速安装

1. 安装并配置 Obsidian：

   • 在 Obsidian 中安装 Local REST API 插件。
   • 在“设置”>“社区插件”中启用该插件。
   • 进入“设置”>“Local REST API”。
   • 复制你的 API 密钥（在步骤 2 中会用到）。

2. 配置你的 AI 工具：

   Claude Desktop

   编辑你的 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   Cursor IDE

   在你的 Cursor 设置中添加以下内容：

   • 项目特定设置：项目目录下的 .cursor/mcp.json
   • 全局设置：主目录下的 ~/.cursor/mcp.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   然后：打开“设置”→“Cursor 设置”→启用 MCP。

   Windsurf IDE

   编辑你的 Windsurf 配置文件：

   • 位置：~/.codeium/windsurf/mcp_config.json

   {
     "mcpServers": {
       "obsidian": {
         "command": "uvx",
         "args": ["obsidian-mcp"],
         "env": {
           "OBSIDIAN_REST_API_KEY": "your-api-key-here"
         }
       }
     }
   }
   

   然后：打开 Windsurf 设置→高级设置→级联→添加服务器→刷新。

   将 your-api-key-here 替换为你从 Obsidian 复制的 API 密钥。

   ⚠️ 重要提示

   如果你使用 HTTPS 或自定义端口，请在 env 部分添加 "OBSIDIAN_API_URL": "https://localhost:27124"。详情请参阅 高级配置。

3. 重启你的 AI 工具 以加载新配置。

大功告成！现在你的 AI 工具可以访问你的 Obsidian 知识库了。

💡 使用建议

此安装方式使用了 uvx，它会自动下载并在隔离环境中运行服务器。大多数用户无需再安装其他东西。如果你没有安装 uv，也可以使用 pipx install obsidian-mcp，并在配置中将命令改为 "obsidian-mcp"。

开发安装

1. 克隆仓库：

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

2. 设置 Python 环境：

# 使用 pyenv（推荐）
pyenv virtualenv 3.12.9 obsidian-mcp
pyenv activate obsidian-mcp

# 或者使用 venv
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

3. 安装依赖项：

pip install -r requirements.txt

4. 设置 Obsidian Local REST API：
   • 在 Obsidian 中安装 Local REST API 插件。
   • 在 Obsidian 设置中启用该插件。
   • 从插件设置中复制 API 密钥。
   • 记录端口号（默认：HTTP 为 27123，HTTPS 为 27124）。
5. 配置环境变量：

export OBSIDIAN_REST_API_KEY="your-api-key-here"
# export OBSIDIAN_API_URL="https://localhost:27124"  # 可选：仅在使用 HTTPS 时设置

6. 添加到 Claude Desktop（用于开发）： 编辑你的 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/obsidian-mcp",
      "env": {
        "PYTHONPATH": "/path/to/obsidian-mcp",
        "OBSIDIAN_REST_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 使用示例

基础用法

# 克隆仓库
git clone https://github.com/natestrong/obsidian-mcp
cd obsidian-mcp

# 设置 Python 环境
# 使用 pyenv（推荐）
pyenv virtualenv 3.12.9 obsidian-mcp
pyenv activate obsidian-mcp

# 或者使用 venv
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

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

# 设置 Obsidian Local REST API
# 在 Obsidian 中安装 Local REST API 插件
# 在 Obsidian 设置中启用该插件
# 从插件设置中复制 API 密钥
# 记录端口号（默认：HTTP 为 27123，HTTPS 为 27124）

# 配置环境变量
export OBSIDIAN_REST_API_KEY="your-api-key-here"
# export OBSIDIAN_API_URL="https://localhost:27124"  # 可选：仅在使用 HTTPS 时设置

# 添加到 Claude Desktop（用于开发）
# 编辑你的 Claude Desktop 配置文件：
# - macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
# - Windows：`%APPDATA%\Claude\claude_desktop_config.json`

# {
#   "mcpServers": {
#     "obsidian": {
#       "command": "/path/to/python",
#       "args": ["-m", "src.server"],
#       "cwd": "/path/to/obsidian-mcp",
#       "env": {
#         "PYTHONPATH": "/path/to/obsidian-mcp",
#         "OBSIDIAN_REST_API_KEY": "your-api-key-here"
#       }
#     }
#   }
# }

高级用法

# 运行测试
# 运行所有测试
python tests/run_tests.py

# 运行特定类型的测试
python tests/run_tests.py unit         # 单元测试（需要 pytest）
python tests/run_tests.py integration  # 集成测试（需要 pytest）
python tests/run_tests.py live         # 使用真实 Obsidian 进行实时测试

# 运行单个测试文件
python tests/test_comprehensive.py     # 完整工作流测试
python tests/test_data_validation.py   # 数据结构验证

📚 详细文档

项目结构

obsidian-mcp/
├── src/
│   ├── server.py           # 主入口点，具有丰富的参数模式
│   ├── tools/              # 工具实现
│   │   ├── note_management.py    # CRUD 操作
│   │   ├── search_discovery.py   # 搜索和导航
│   │   ├── organization.py       # 标签、移动、元数据
│   │   └── link_management.py    # 反向链接、出站链接、断链
│   ├── models/             # 用于验证的 Pydantic 模型
│   │   └── obsidian.py    # 笔记、搜索结果、知识库项模型
│   ├── utils/              # 共享实用工具
│   │   ├── obsidian_api.py      # REST API 客户端包装器
│   │   ├── validators.py        # 路径验证、清理
│   │   └── validation.py        # 全面的参数验证
│   └── constants.py       # API 端点、默认值、增强的错误消息
├── tests/
│   ├── run_tests.py       # 智能测试运行器
│   ├── test_unit.py       # 带模拟的单元测试
│   ├── test_integration.py # 集成测试
│   ├── test_live.py       # 实时 API 测试
│   ├── test_comprehensive.py # 完整工作流验证
│   └── test_data_validation.py # 返回值测试
├── docs/                  # 额外的文档
├── requirements.txt       # Python 依赖项
├── CLAUDE.md             # Claude 代码说明
└── README.md

可用工具

笔记管理

read_note

读取特定笔记的内容和元数据。 参数：

• path：笔记的路径（例如，"Daily/2024-01-15.md"） 返回值：

{
  "path": "Daily/2024-01-15.md",
  "content": "# 日常笔记\n\n这里是内容...",
  "metadata": {
    "tags": ["daily", "journal"],
    "aliases": [],
    "frontmatter": {}
  }
}

create_note

创建新笔记或更新现有笔记。 参数：

• path：笔记的创建路径
• content：笔记的 Markdown 内容（建议添加标签以进行组织）
• overwrite（默认：false）：是否覆盖现有笔记 最佳实践：
• 创建笔记时添加相关标签，以保持组织性。
• 使用 list_tags 查看现有标签，以保持一致性。
• 标签可以作为内联哈希标签（#tag）或前置元数据添加。

update_note

更新现有笔记的内容。 ⚠️ 重要提示：默认情况下，此工具会替换整个笔记内容。如果需要保留现有内容，请先读取笔记。 参数：

• path：要更新的笔记路径
• content：新的 Markdown 内容（除非使用追加模式，否则将替换现有内容）
• create_if_not_exists（默认：false）：如果笔记不存在则创建
• merge_strategy（默认："replace"）：处理内容的方式
  • "replace"：覆盖整个笔记内容（默认）
  • "append"：将新内容添加到现有内容的末尾 安全更新模式：

1. 始终先读取以保留内容。
2. 根据需要修改内容。
3. 使用完整的新内容进行更新。
4. 或者使用追加模式将内容添加到末尾。

delete_note

从知识库中删除笔记。 参数：

• path：要删除的笔记路径

搜索和发现

search_notes

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

• query：搜索查询（支持 Obsidian 搜索语法）
• context_length（默认：100）：匹配项周围显示的字符数 搜索语法：
• 文本搜索："机器学习"
• 标签搜索：tag:project 或 tag:#project
• 路径搜索：path:Daily/
• 组合搜索：tag:urgent TODO

search_by_date

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

• date_type（默认："modified"）：可以是 "created" 或 "modified"
• days_ago（默认：7）：回顾的天数
• operator（默认："within"）：可以是 "within"（过去 N 天）或 "exactly"（正好 N 天前） 返回值：

{
  "query": "过去 7 天内修改的笔记",
  "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")
• "哪些笔记正好在 2 天前被修改了？" → search_by_date("modified", 2, "exactly")

list_notes

列出知识库中的笔记，可选择递归遍历。 参数：

• 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

列出知识库中的文件夹，可选择递归遍历。 参数：

• 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

在知识库中创建新文件夹，包括路径中的所有父文件夹。 参数：

• folder_path：要创建的文件夹路径（例如，"Apple/Studies/J71P"）
• create_placeholder（默认：true）：是否创建占位符文件 返回值：

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

注意：此工具将创建所有必要的父文件夹。例如，如果 "Apple" 存在但 "Studies" 不存在，它将创建 "Studies" 和 "J71P"。

move_note

将笔记移动到新位置。 参数：

• source_path：笔记的当前路径
• destination_path：笔记的新路径
• update_links（默认：true）：更新其他笔记中的链接（未来增强功能）

move_folder

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

• source_folder：当前文件夹路径（例如，"Projects/Old"）
• destination_folder：新文件夹路径（例如，"Archive/Projects/Old"）
• 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：要添加的标签列表（不带 # 前缀）

update_tags

更新笔记上的标签 - 可以替换所有标签或与现有标签合并。 参数：

• path：笔记的路径
• tags：要设置的新标签（不带 # 前缀）
• merge（默认：false）：如果为 true，则添加到现有标签；如果为 false，则替换所有标签 非常适合 AI 工作流：

用户："告诉我这篇笔记是关于什么的，并添加适当的标签"
AI：[读取笔记] "这篇笔记是关于机器学习研究的..."
AI：[使用 update_tags 设置标签：["ai", "research", "neural-networks"]]

remove_tags

从笔记的前置元数据中删除标签。 参数：

• path：笔记的路径
• tags：要删除的标签列表

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
  }
}

list_tags

列出知识库中使用的所有唯一标签及其使用统计信息。 参数：

• include_counts（默认：true）：包括每个标签的使用计数
• sort_by（默认："name"）：按 "name" 或 "count" 排序 返回值：

{
  "total_tags": 25,
  "tags": [
    {"name": "project", "count": 42},
    {"name": "meeting", "count": 38},
    {"name": "idea", "count": 15}
  ]
}

性能说明：

• 对于小型知识库（<1000 篇笔记）速度较快。
• 对于大型知识库可能需要几秒钟。
• 使用并发批处理进行优化。

链接管理

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

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

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 研究",
      "link_type": "wiki",
      "context": "...今天正在进行 [[AI 研究]] 项目..."
    }
  ]
}

使用场景：

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

get_outgoing_links

列出特定笔记中的所有链接。 参数：

• path：要提取链接的笔记路径
• check_validity（默认：false）：是否检查链接的笔记是否存在 返回值：

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

使用场景：

• 了解笔记引用的内容。
• 在移动/删除笔记之前检查笔记依赖项。
• 探索索引或中心笔记的结构。

find_broken_links

查找知识库、特定目录或单个笔记中的所有断链。 参数：

• directory（可选）：要检查的特定目录（默认为整个知识库）
• 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": "旧项目",
      "link_type": "wiki"
    }
  ]
}

使用场景：

• 重命名或删除笔记后。
• 定期进行知识库维护。
• 重组文件夹结构之前。

🔧 技术细节

运行测试

# 运行所有测试
python tests/run_tests.py

# 运行特定类型的测试
python tests/run_tests.py unit         # 单元测试（需要 pytest）
python tests/run_tests.py integration  # 集成测试（需要 pytest）
python tests/run_tests.py live         # 使用真实 Obsidian 进行实时测试

# 运行单个测试文件
python tests/test_comprehensive.py     # 完整工作流测试
python tests/test_data_validation.py   # 数据结构验证

使用 MCP Inspector 进行测试

1. 确保 Obsidian 正在运行，并且 Local REST API 插件已启用。
2. 运行 MCP Inspector：

npx @modelcontextprotocol/inspector python -m src.server

3. 打开 Inspector UI：在 http://localhost:5173 打开。
4. 交互式测试工具：使用你实际的知识库进行测试。

与 Claude Desktop 集成

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

增强的错误处理

服务器提供详细、可操作的错误消息，以帮助 AI 系统从错误中恢复。

示例错误消息

无效路径：

无效的笔记路径：'../../../etc/passwd'。
有效路径必须：1) 以 .md 或 .markdown 结尾；2) 使用正斜杠（例如，'folder/note.md'）；
3) 不包含 '..' 或不以 '/' 开头；4) 不超过 255 个字符。
示例：'Daily/2024-01-15.md' 或 'Projects/My Project.md'

空搜索查询：

搜索查询不能为空。
有效查询：1) 关键字：'机器学习'；
2) 标签：'tag:#project'；3) 路径：'path:Daily/'；
4) 组合：'tag:#urgent TODO'

无效日期参数：

无效的 date_type：'invalid'。
必须是 'created' 或 'modified'。
使用 'created' 按创建日期查找笔记，使用 'modified' 按最后编辑日期查找笔记。

故障排除

"连接被拒绝" 错误

• 确保 Obsidian 正在运行。
• 验证 Local REST API 插件已启用。
• 检查端口是否匹配（默认：HTTP 为 27123，HTTPS 为 27124）。
• 确认 API 密钥正确。
• 增强的错误消息将显示正在使用的精确 URL 和端口。

标签未显示

• 确保标签格式正确（带或不带 # 前缀）。
• 检查 Local REST API 插件是否为最新版本。
• 前置元数据中的标签应采用 YAML 数组格式：tags: [tag1, tag2]。
• 内联标签应使用 # 前缀：#project #urgent。

"证书验证失败" 错误

• 这是 Local REST API 的自签名证书的预期情况。
• 服务器会自动处理此问题。

"模块未找到" 错误

• 确保你的虚拟环境已激活。
• 从项目根目录运行：python -m src.server。
• 验证 PYTHONPATH 包含项目目录。

列出笔记时结果为空

• 使用 list_notes 时指定目录（例如，"Daily"，"Projects"）。
• 根目录列表需要递归实现。
• 检查笔记是否在子目录中。

标签未更新

• 确保笔记有 YAML 前置元数据部分以使用前置元数据标签。
• 前置元数据必须包含 tags: 字段（即使为空）。
• 服务器现在可以正确读取前置元数据标签和内联哈希标签。

AI 助手的最佳实践

防止数据丢失

1. 更新前始终先读取：默认情况下，update_note 工具会替换内容。
2. 使用追加模式进行添加：向现有笔记添加内容时，使用 merge_strategy="append"。
3. 检查笔记是否存在：在修改之前使用 read_note 验证笔记是否存在。
4. 明确覆盖操作：仅在有意替换内容时使用 overwrite=true。

推荐工作流

安全的笔记编辑：

1. 首先读取现有笔记。
2. 根据需要修改内容。
3. 使用完整的新内容进行更新。

添加到日常笔记：

• 使用 merge_strategy="append" 添加条目，而不会丢失现有内容。

创建新笔记：

• 使用 create_note 并将 overwrite=false（默认）以防止意外覆盖。
• 添加相关标签以保持组织性。
• 使用 list_tags 查看现有标签，避免创建重复标签。

使用标签进行组织：

• 在创建新标签之前，使用 list_tags 检查现有标签。
• 保持一致的命名（例如，使用 "project" 而不是 "projects"）。
• 使用标签实现强大的搜索和过滤功能。

安全考虑

• 保密你的 API 密钥 - 切勿将其提交到版本控制中。
• 服务器验证所有路径，以防止目录遍历攻击。
• 与 Obsidian 的通信默认使用 HTTP（仅本地连接）或使用自签名证书的 HTTPS。
• 服务器仅通过 REST API 接受本地连接。

开发

代码风格

• 使用 FastMCP 框架实现 MCP。
• 使用 Pydantic 模型进行类型安全和验证。
• 采用模块化架构，职责分离。
• 全面的错误处理和用户友好的消息。

添加新工具

1. 在 src/tools/ 下的适当模块中创建工具函数。
2. 如果需要，在 src/models/ 中添加 Pydantic 模型。
3. 使用 @mcp.tool() 装饰器在 src/server.py 中注册工具。
4. 包含全面的文档字符串。
5. 在 tests/ 中添加测试。
6. 在部署之前使用 MCP Inspector 进行测试。

变更日志

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-01-09)

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

v1.1.3 (2025-01-09)

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

v1.1.2 (2025-01-09)

• 修复 PyPI 包文档。

v1.1.1 (2025-01-06)

• 首次 PyPI 发布。

发布（维护者适用）

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

# 1. 在 pyproject.toml 中更新版本号
# 2. 清理旧构建
rm -rf dist/ build/ *.egg-info/

# 3. 构建包
python -m build

# 4. 检查包
twine check dist/*

# 5. 上传到 PyPI
twine upload dist/* -u __token__ -p $PYPI_API_KEY

# 6. 创建并推送 git 标签
git tag -a v1.1.7 -m "发布版本 1.1.7"
git push origin v1.1.7

用户可以使用以下命令进行安装和运行：

# 使用 uvx（推荐 - 无需安装）
uvx obsidian-mcp

# 或者使用 pipx 全局安装
pipx install obsidian-mcp
obsidian-mcp

# 或者使用 pip 安装
pip install obsidian-mcp
obsidian-mcp

配置

高级配置

如果你使用非标准设置，可以使用以下环境变量自定义服务器行为：

• OBSIDIAN_API_URL - 覆盖默认的 API 端点（默认：http://127.0.0.1:27123）
  • 如果你运行的是 HTTPS 端点（例如，https://localhost:27124），请使用此选项。
  • 或者如果你在 Local REST API 插件设置中更改了端口号。
  • 默认使用 HTTP 端点，以便于设置。
  • 注意：尾随斜杠会自动处理（http://127.0.0.1:27123 和 http://127.0.0.1:27123/ 都可以）。

HTTPS 或非标准配置示例

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": ["obsidian-mcp"],
      "env": {
        "OBSIDIAN_REST_API_KEY": "your-api-key-here",
        "OBSIDIAN_API_URL": "https://localhost:27124"
      }
    }
  }
}

贡献

1. 分叉仓库。
2. 创建功能分支（git checkout -b feature/amazing-tool）。
3. 为新功能编写测试。
4. 确保所有测试通过。
5. 提交更改（git commit -m '添加出色的工具'）。
6. 推送到分支（git push origin feature/amazing-tool）。
7. 打开拉取请求。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• Anthropic 创建了模型上下文协议。
• Obsidian 团队开发了出色的笔记应用。
• coddingtonbear 开发了 Local REST API 插件。
• dsp-ant 开发了 FastMCP 框架。