Obsidian Mcp

笔记 Python

🚀 Obsidian MCP 服务器

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

🚀 快速开始

快速安装

安装并配置 Obsidian：
- 在 Obsidian 中安装 Local REST API 插件。
- 在“设置”>“社区插件”中启用该插件。
- 进入“设置”>“Local REST API”。
- 复制你的 API 密钥（在步骤 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"。详情请参阅高级配置。
重启你的 AI 工具 以加载新配置。

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

💡 使用建议

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

立即试用

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

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

开发安装

克隆仓库：

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

✨ 主要特性

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

📦 安装指南

快速安装

安装并配置 Obsidian：
- 在 Obsidian 中安装 Local REST API 插件。
- 在“设置”>“社区插件”中启用该插件。
- 进入“设置”>“Local REST API”。
- 复制你的 API 密钥（在步骤 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"。详情请参阅高级配置。
重启你的 AI 工具 以加载新配置。

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

💡 使用建议

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

开发安装

克隆仓库：

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

💻 使用示例

基础用法

# 克隆仓库
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"：将新内容添加到现有内容的末尾 安全更新模式：

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

`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 进行测试

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

npx @modelcontextprotocol/inspector python -m src.server

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

与 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 助手的最佳实践

防止数据丢失

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

安全考虑

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

开发

代码风格

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

添加新工具

在 src/tools/ 下的适当模块中创建工具函数。
如果需要，在 src/models/ 中添加 Pydantic 模型。
使用 @mcp.tool() 装饰器在 src/server.py 中注册工具。
包含全面的文档字符串。
在 tests/ 中添加测试。
在部署之前使用 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"
}
}
}
}

贡献

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

📄 许可证

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

致谢

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

0 条评论
分类：笔记

Obsidian Mcp

🚀 Obsidian MCP 服务器

🚀 快速开始

快速安装

立即试用

开发安装

✨ 主要特性

📦 安装指南

快速安装

开发安装

💻 使用示例

基础用法

高级用法

📚 详细文档

项目结构

可用工具

笔记管理

read_note

create_note

update_note

delete_note

搜索和发现

search_notes

search_by_date

list_notes

list_folders

组织管理

create_folder

move_note

move_folder

add_tags

update_tags

remove_tags

get_note_info

list_tags

链接管理

get_backlinks

get_outgoing_links

find_broken_links

🔧 技术细节

运行测试

使用 MCP Inspector 进行测试

与 Claude Desktop 集成

增强的错误处理

示例错误消息

故障排除

"连接被拒绝" 错误

标签未显示

"证书验证失败" 错误

"模块未找到" 错误

列出笔记时结果为空

标签未更新

AI 助手的最佳实践

防止数据丢失

推荐工作流

安全考虑

开发

代码风格

添加新工具

变更日志

v1.1.7 (2025-01-10)

v1.1.6 (2025-01-10)

v1.1.5 (2025-01-09)

v1.1.4 (2025-01-09)

v1.1.3 (2025-01-09)

v1.1.2 (2025-01-09)

v1.1.1 (2025-01-06)

发布（维护者适用）

配置

高级配置

HTTPS 或非标准配置示例

贡献

📄 许可证

致谢

0 个评论

相似服务问题

相关AI产品

热议话题 »

`read_note`

`create_note`

`update_note`

`delete_note`

`search_notes`

`search_by_date`

`list_notes`

`list_folders`

`create_folder`

`move_note`

`move_folder`

`add_tags`

`update_tags`

`remove_tags`

`get_note_info`

`list_tags`

`get_backlinks`

`get_outgoing_links`

`find_broken_links`