Obsidian MCP服务器

自定义黑曜石MCP服务器

用于黑曜石保险库操作的全面模型上下文协议（MCP）服务器，针对以下方面进行了优化 Zettelkasten笔记创建工作流程。适用于支持MCP的任何LLM（Claude、Perplexity等）。

概述

此MCP服务器连接到 黑名单本地REST API插件 并提供12个强大的工具：

• 文件操作：列出、读取和管理vault中的文件
• 内容操作：创建、附加和精确编辑注释
• 搜索：在您的保险库中查找相关笔记
• 元数据管理：标签、封面和注释属性

专为 实践者盒 他们希望人工智能在创建原子笔记、寻找联系和维护知识图谱方面提供帮助。

特性

✅ Zettelkasten优化：专为原子笔记创建和链接而设计的工具
✅ LLM不可知论：适用于任何兼容MCP的LLM
✅ 默认安全：CREATE模式不会覆盖现有笔记
✅ 强大的搜索功能：在创建重复项之前查找现有笔记
✅ 精确编辑：在特定标题或块中插入内容
✅ 元数据丰富：全面的前台和标签管理

先决条件

1. 黑曜石 随着 本地REST API插件 已安装并配置
2. Python 3.10+
3. 紫外线 （可选，但建议用于管理Python环境）

安装

1.安装MCP服务器

使用 uv （推荐）：

cd custom-obsidian-mcp
uv sync

或者使用pip：

cd custom-obsidian-mcp
pip install -e .

2.设置Obsidian本地REST API

1. 在Obsidian中安装“本地REST API”插件
2. 在设置中启用插件→ 社区插件
3. 转到插件设置并复制您的API密钥
4. 注意端口（默认值：27124）

3.配置环境变量

创建一个 .env 文件或设置这些变量：

export OBSIDIAN_API_KEY="your-api-key-here"
export OBSIDIAN_HOST="127.0.0.1"  # Usually localhost
export OBSIDIAN_PORT="27124"      # Default port

LLM客户端的配置

克劳德桌面（桌面应用程序）

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/uvx",
      "args": ["custom-obsidian-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

或者，如果使用pip安装：

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["-m", "custom_obsidian_mcp.server"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}

困惑或其他MCP客户端

使用适合客户格式的类似配置结构。

可用工具

文件操作

obsidian_list_files_in_vault

列出vault根目录中的所有文件和目录。

# No parameters needed

obsidian_list_files_in_dir

列出特定目录的内容。

{
  "dirpath": "Zettelkasten"  # Empty string for root
}

obsidian_get_file_contents

读取单个文件的完整内容。

{
  "filepath": "Zettelkasten/202411061234.md"
}

obsidian_batch_get_file_contents

一次读取多个文件（最多20个）。

{
  "filepaths": [
    "Zettelkasten/note1.md",
    "Zettelkasten/note2.md"
  ]
}

搜索操作

obsidian_simple_search

使用上下文在所有vault文件中进行文本搜索。

{
  "query": "systems thinking",
  "context_length": 100  # Optional, default 100
}

obsidian_complex_search

基于JsonLogic的高级搜索。

{
  "query": {"glob": ["*.md", {"var": "path"}]}
}

内容操作

obsidian_write_note

使用可选的frontmatter创建或修改笔记。

{
  "filepath": "Zettelkasten/202411061234 Systems Thinking.md",
  "content": "# Systems Thinking\n\nContent here...",
  "mode": "create",  # create|overwrite|append|prepend
  "frontmatter": {
    "tags": ["zettelkasten", "systems"],
    "created": "2024-11-06"
  }
}

模式：

• create：仅创建新文件（不会覆盖）
• overwrite：替换整个文件
• append：添加到末尾
• prepend：添加到开头

obsidian_append_content

快速附加到文件（如果不存在则创建）。

{
  "filepath": "Zettelkasten/note.md",
  "content": "\n## New Section\n\nNew content..."
}

obsidian_patch_content

在笔记中的特定位置插入内容。

{
  "filepath": "Zettelkasten/note.md",
  "target_type": "heading",  # heading|block|frontmatter
  "target": "Related Concepts/Subsection",
  "operation": "append",  # append|prepend|replace
  "content": "New related concept..."
}

目标类型：

• heading：导航到航向路径（例如“节/小节”）
• block：使用块引用（例如，“^块id”）
• frontmatter：更新特定前端字段

obsidian_delete_file

删除文件或目录（需要确认）。

{
  "filepath": "Zettelkasten/old-note.md",
  "confirm": true  # Must be true to proceed
}

元数据操作

obsidian_get_frontmatter

从笔记中提取YAML frontmatter。

{
  "filepath": "Zettelkasten/note.md"
}

obsidian_update_frontmatter

更新frontmatter而不修改内容。

{
  "filepath": "Zettelkasten/note.md",
  "updates": {
    "tags": ["zettelkasten", "new-tag"],
    "status": "published"
  }
}

obsidian_manage_tags

添加、删除或列出标签。

{
  "filepath": "Zettelkasten/note.md",
  "action": "add",  # add|remove|list
  "tags": ["systems-thinking", "mental-models"]
}

obsidian_get_notes_info

获取多个笔记的元数据（最多50个）。

{
  "filepaths": [
    "Zettelkasten/note1.md",
    "Zettelkasten/note2.md"
  ]
}

返回：标签、创建日期、大小和其他元数据。

Zettelkasten工作流示例

创建新的原子笔记

1. 搜索现有的相关笔记：

   复制

   Use obsidian_simple_search with query "systems thinking"
   

2. 阅读相关说明：

   复制

   Use obsidian_batch_get_file_contents with discovered notes
   

3. 创建新的原子注释：

   复制

   Use obsidian_write_note:
   - filepath: "Zettelkasten/202411061234 Systems Thinking Core Concept.md"
   - content: Your atomic note content
   - mode: "create" (safe - won't overwrite)
   - frontmatter: {tags: ["zettelkasten", "systems"], created: "2024-11-06"}
   

链接相关笔记

1. 在主题组中查找注释：

   复制

   Use obsidian_simple_search or obsidian_get_notes_info
   

2. 将连接添加到现有注释：

   复制

   Use obsidian_patch_content:
   - target_type: "heading"
   - target: "Related Concepts"
   - operation: "append"
   - content: "- [[202411061234 Systems Thinking Core Concept]]"
   

用标签组织

1. 检查当前标签：

   复制

   Use obsidian_manage_tags with action: "list"
   

2. 添加主题标签：

   复制

   Use obsidian_manage_tags with action: "add"
   

最佳实践

对于Zettelkasten

• 始终先搜索：使用 obsidian_simple_search 在创建新笔记以避免重复之前
• 原子笔记：每张便条一个想法，标题清晰
• 自由链接：使用 obsidian_patch_content 添加连接
• 标签一致：使用 obsidian_manage_tags 主题组织
• 使用CREATE模式：默认为 mode="create" 防止意外覆盖

为了安全

• CREATE模式为默认模式：不会覆盖现有笔记
• 需要确认：破坏性操作需要明确确认
• 在开发库中测试：在Zettelkasten上使用之前，先在测试库中尝试工具

故障排除

连接错误

错误： “GET/vault/连接错误”

解决：

1. 验证Obsidian是否正在运行
2. 检查本地REST API插件是否已启用
3. 验证API密钥是否正确
4. 检查端口是否与插件设置匹配（默认值：27124）

身份验证错误

错误： “身份验证失败”

解决：

1. 检查 OBSIDIAN_API_KEY 环境变量
2. 在插件设置中重新生成API密钥
3. 确保API密钥中没有额外的空格

文件未找到

错误： “找不到资源”

解决：

1. 验证文件路径是否相对于vault根目录
2. 检查文件是否存在：使用 obsidian_list_files_in_dir
3. 确保文件扩展名正确（例如。， .md)

建筑

custom-obsidian-mcp/
├── src/
│   └── custom_obsidian_mcp/
│       ├── __init__.py
│       ├── server.py          # FastMCP server with all tools
│       └── obsidian_client.py # REST API client
├── pyproject.toml             # Project configuration
└── README.md

关键组件

• FastMCP：带有Pydantic验证的现代Python MCP框架
• 黑曜石客户端：用于REST API通信的异步HTTP客户端
• Pydantic模型：所有工具的类型安全输入验证
• 错误处理：可操作的错误消息指导正确使用

发展

运行测试

# Verify Python syntax
python -m py_compile src/custom_obsidian_mcp/server.py

# Test basic import
python -c "from custom_obsidian_mcp.server import mcp; print('OK')"

添加新工具

1. 定义Pydantic输入模型
2. 添加工具功能 @mcp.tool 装饰器
3. 包括适当的注释（readOnlyHint等）
4. 添加全面的文档字符串
5. 实施错误处理

贡献

欢迎投稿！拜托：

1. 遵循现有代码样式
2. 添加Pydantic模型进行验证
3. 包含带有示例的文档字符串
4. 使用Obsidian本地REST API进行测试

许可证

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

致谢

• 建立在 MCP Python SDK
• 灵感来自 马库斯·普芬德斯坦的mcp黑曜石
• 用途 黑名单本地REST API

支持

对于问题或疑问：

1. 检查故障排除部分
2. 验证Obsidian本地REST API是否工作
3. 首先使用简单工具进行测试（list_files_in_vault）
4. 打开一个包含错误消息和配置的问题

记笔记快乐！ 📝✨