obsidian-helper

Obsidian Helper - Intelligent Note-Taking Assistant

This is an intelligent assistant deeply integrated with Obsidian MCP, offering three core features to boost your note-taking efficiency.

⚡ Must-read for first use: automatic detection and configuration guide

Before executing any feature, Claude must first execute STEP 0

STEP 0: MCP 连接检测（每次会话首次使用时执行）
├─ 尝试调用 obsidian_list_files_in_vault()
├─ 如果成功 → 继续执行用户请求的功能
└─ 如果失败 → 进入【配置引导流程】

Configuration guide flow (all prompts in Chinese)

When the MCP connection fails, Claude must display the following guide information to the user:

Obsidian MCP is detected as not connected, let me help you configure it!

📋 Configuration steps

Step 1: Install the Obsidian plugin

Open Obsidian → Settings → Third-party plugins
Turn off "Safe mode"
Click "Browse", search for Local REST API
Install and enable the plugin

Step 2: Get the API Key

In Obsidian settings, find the Local REST API plugin settings
Click "Copy API Key" to copy your API Key
Note down the port number (the default is 27124）

Step 3: Configure Claude Code MCP

Run the following command in the terminal, replacing 你的API_KEY with the Key you just copied:

# 创建 MCP 配置目录（如果不存在）
mkdir -p ~/.claude

# 添加 Obsidian MCP 配置
cat >> ~/.claude/mcp.json << 'EOF'
{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "你的API_KEY",
        "OBSIDIAN_HOST": "https://127.0.0.1:27124"
      }
    }
  }
}
EOF

Or manually edit ~/.claude/mcp.json：

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "你的API_KEY",
        "OBSIDIAN_HOST": "https://127.0.0.1:27124"
      }
    }
  }
}

Step 4: Restart Claude Code

# 完全退出 Claude Code，然后重新启动
claude

Step 5: Verify the connection

After restarting, enter the command you want again (such as /daily), and I will automatically verify whether the connection is successful.

❓ Frequently asked questions

Problem	Solution
Plugin not found	Make sure the Obsidian version is ≥ 1.0.0
Connection refused	Check whether Obsidian is running
API Key invalid	Copy the Key again in the plugin settings
Port conflict	Change the port in the plugin settings and update mcp.json

Need help? Tell me the specific error message you encountered, and I will help you solve it.

Prompt after a successful connection

When the MCP connection is successful, Claude should briefly confirm:

✅ Obsidian 已连接！检测到你的知识库，现在开始执行 [功能名称]...

🎯 Core feature overview

Command	Function	Use case
`/daily`	Intelligent journal assistant	At the start of each day, quickly kick off the day
`/capture <主题>`	Knowledge capture	Record ideas and notes at any time
`/review [period]`	Periodic review	Summarize and review regularly

🏗️ Recommended Vault structure (PARA + Zettelkasten)

Vault/
├── 00_Inbox/                 # 随手记
│   └── AI/                   # 【重要】AI 专用落地区
├── 10_Projects/              # 有截止时间的项目
├── 20_Areas/                 # 长期领域（学习/健康/职业）
├── 30_Resources/             # 资料库
│   └── Products/             # 产品卡片
├── 40_Zettels/               # 永久笔记（结论/洞见）
├── 90_Archive/               # 归档
├── 99_System/Templates/      # 模板
└── Daily Notes/              # 日记

⚠️ Three hard rules for AI writing

Claude must comply with the following rules:

Rule 1: AI-specific landing zone

新建笔记默认位置: 00_Inbox/AI/
用户确认后才移动到其他位置

Rule 2: Append-only writing

✅ 用 obsidian_append_content 追加
✅ 用 obsidian_patch_content 在指定标题下追加
❌ 不要重写整篇笔记

Rule 3: Properties whitelist

# 只允许写这些字段，不能发明新字段
---
type: note | product | project | zettel
title: ""
tags: []
status: active | done | archived
created: {{date}}
---

📋 Feature 1: /daily - Intelligent journal assistant

Trigger conditions

User input /daily
User says "start today's journal", "today's journal", "daily note"

Execution flow

STEP 0: MCP 连接检测（见上方）

STEP 1: 获取日记信息
├─ 尝试 obsidian_get_periodic_note(period: "daily")
├─ 如果失败，使用 obsidian_list_files_in_dir("Daily Notes") 查找今日文件
├─ 使用 obsidian_get_recent_periodic_notes 或手动获取昨日日记
└─ 检查日记是否已存在

STEP 2: 分析昨日内容
├─ 读取昨日日记内容
├─ 提取未完成的 TODO（正则匹配 `- \[ \]`）
├─ 识别重要事项
└─ 生成简要总结

STEP 3: 生成今日日记
├─ 如果今日日记不存在，创建新日记
├─ 使用标准模板结构
├─ 自动填入：
│   ├─ 昨日未完成事项 → 今日待办
│   ├─ 日期和星期（中文格式）
│   └─ 基础模板结构
└─ 使用 obsidian_append_content 写入

STEP 4: 向用户报告
├─ 显示日记创建/更新状态
├─ 列出继承的未完成任务数量
└─ 询问是否需要补充内容

Diary Template Structure

---
date: {{YYYY-MM-DD}}
tags: [daily]
---

# {{星期}}, {{月}} {{日}}, {{年}}

## 今日重点

> [!tip] Focus
>

## 任务

### 从昨日继承
{{yesterday_incomplete_todos}}

### 必须完成
- [ ]

### 应该完成
- [ ]

### 可以完成
- [ ]

## 今日笔记

### 上午


### 下午


### 晚间


## 想法与灵感


## 今日创建的链接


## 晚间反思

### 顺利的地方


### 可以改进的地方


### 感恩

Usage Example

User Input: /daily or 开始今日日记

Claude Execution:

Check MCP connection ✓
Get today's diary (e.g., 2026-01-19)
Get yesterday's diary, extract unfinished items
Create/update today's diary
Reply: "✅ Today's diary has been created! Inherited X unfinished tasks from yesterday."

📋 Feature 2: /capture - Quick Knowledge Capture

Trigger Conditions

User input /capture <主题> or /capture <主题> <内容>
User says "note this down", "capture", "add a note", "capture"

Execution Flow

STEP 0: MCP 连接检测

STEP 1: 解析用户输入
├─ 提取主题关键词（第一个词或引号内容）
├─ 提取要记录的内容（主题之后的所有文本）
└─ 如果只有主题没有内容，询问用户要记录什么

STEP 2: 搜索现有笔记
├─ 使用 obsidian_simple_search(query: 主题) 搜索
├─ 分析搜索结果的相关性
└─ 按相关度排序

STEP 3: 决策与执行
├─ 情况A：找到高度相关笔记（标题包含主题）
│   ├─ 告诉用户：「找到相关笔记《XXX》，是否追加到此笔记？」
│   ├─ 用户确认后，使用 obsidian_patch_content 追加
│   └─ 追加格式：## {{时间戳}} 捕获\n{{内容}}
│
├─ 情况B：找到部分相关笔记
│   ├─ 列出最相关的 3 个笔记
│   ├─ 询问：「选择追加到哪个笔记，或创建新笔记？」
│   └─ 根据用户选择执行
│
└─ 情况C：未找到相关笔记
    ├─ 告诉用户：「未找到相关笔记，将创建新笔记」
    ├─ 询问存放位置（列出现有文件夹）
    └─ 使用 obsidian_append_content 创建

STEP 4: 确认完成
└─ 显示：「✅ 已保存到《XXX》」

Capture Content Format

## 2026-01-19 14:30 捕获

{{用户输入的内容}}

---

Usage Example

Example 1:

用户: /capture API设计 RESTful API 应该使用名词而非动词

Claude: Search → Found "API Design Best Practices.md" → Ask for confirmation → Append content

Example 2:

用户: /capture 新想法

Claude: "What do you want to record?" → User input → Search → Process

📋 Feature 3: /review - Periodic Review Generator

Trigger Conditions

User input /review or /review weekly or /review monthly
User says "weekly review", "monthly summary", "retrospective", "review"

Execution Flow

STEP 0: MCP 连接检测

STEP 1: 确定回顾周期
├─ 解析参数：daily / weekly（默认）/ monthly
└─ 计算时间范围

STEP 2: 收集数据
├─ 获取周期内的日记文件
│   ├─ 尝试 obsidian_get_recent_periodic_notes
│   └─ 备选：obsidian_list_files_in_dir + 日期过滤
├─ 使用 obsidian_batch_get_file_contents 批量读取
├─ 使用 obsidian_get_recent_changes 获取活跃文件
└─ 提取所有相关内容

STEP 3: 分析内容
├─ 统计任务完成情况
│   ├─ 已完成：匹配 `- \[x\]`
│   └─ 未完成：匹配 `- \[ \]`
├─ 提取重要事件和成就
├─ 识别高频主题词
├─ 发现知识关联
└─ 生成洞察

STEP 4: 生成报告
├─ 使用对应周期的模板
├─ 填充统计数据
├─ 添加分析内容
├─ 保存到 Daily Notes/ 文件夹
│   ├─ 周报：YYYY-WXX 周回顾.md
│   └─ 月报：YYYY-MM 月度回顾.md
└─ 使用 obsidian_append_content 写入

STEP 5: 展示结果
├─ 显示回顾摘要
├─ 列出关键数据
└─ 询问是否需要修改或补充

Weekly Review Template

# {{年}}-W{{周}} 周回顾 | {{日期范围}}

## 📊 数据概览
| 指标 | 数值 |
|------|------|
| 📝 笔记数量 | {{count}} |
| ✅ 完成任务 | {{completed}} |
| ⏳ 未完成任务 | {{incomplete}} |
| 📂 活跃文件 | {{active}} |

## 🏆 本周成就
{{achievements}}

## 📋 任务总结

### ✅ 已完成
{{completed_list}}

### ⏳ 待继续
{{incomplete_list}}

## 💡 关键洞察
{{insights}}

## 🔗 知识连接
本周涉及的主要主题：{{themes}}

## 🎯 下周重点
1.
2.
3.

## 📝 反思
### 做得好的地方

### 可以改进的地方

---
*生成时间: {{timestamp}}*

🔧 Configuration Options

Users can create _config/obsidian-helper.md in the Obsidian vault for custom configuration:

# Obsidian Helper 配置

## 日记设置
- 日记文件夹: Daily Notes/
- 日记格式: YYYY-MM-DD
- 周回顾格式: YYYY-[W]ww

## 捕获设置
- 默认捕获文件夹: Resources/
- 自动添加时间戳: true

## 回顾设置
- 默认回顾周期: weekly
- 回顾保存位置: Daily Notes/

Before executing features, Claude should check whether this configuration file exists and read the settings.

🛠️ Technical Implementation

Dependent MCP Tools

Tool	Purpose	Required
`obsidian_list_files_in_vault`	Check connection, list vault structure	✅
`obsidian_list_files_in_dir`	List directory files	✅
`obsidian_get_file_contents`	Read file content	✅
`obsidian_batch_get_file_contents`	Batch read	✅
`obsidian_simple_search`	Text search	✅
`obsidian_append_content`	Create/append content	✅
`obsidian_patch_content`	Precise editing	⚪
`obsidian_get_periodic_note`	Get periodic notes	⚪
`obsidian_get_recent_periodic_notes`	Recent periodic notes	⚪
`obsidian_get_recent_changes`	Recently modified	⚪

Error Handling Strategy

Error Type	Handling Method
MCP not connected	Show full configuration guide (see above)
File does not exist	Create automatically
API unavailable	Use alternative methods (e.g., direct file operations)
Search no results	Prompt to create a new note

📚 Quick Reference

/daily                    → 启动今日日记，继承昨日未完成
/capture <主题>           → 快速捕获到相关笔记
/capture <主题> <内容>    → 捕获指定内容
/review                   → 生成周回顾（默认）
/review daily             → 生成日回顾
/review weekly            → 生成周回顾
/review monthly           → 生成月回顾

🆘 Help Command

When the user enters the following, display help information:

obsidian help
obsidian 帮助
/daily help
怎么用 obsidian helper

Display content:

📖 Obsidian Helper 使用指南

🗓️ /daily - 智能日记
   自动创建今日日记，继承昨日未完成任务

📝 /capture <主题> [内容] - 知识捕获
   快速记录想法到相关笔记
   示例：/capture API设计 REST要用名词

📊 /review [weekly|monthly] - 周期回顾
   自动分析笔记，生成回顾报告

⚙️ 配置问题？
   输入「配置 obsidian」查看 MCP 配置指南

Obsidian Helper v1.1.0 - Making notes smarter

About this skill

⚡ Must-read for first use: automatic detection and configuration guide

Before executing any feature, Claude must first execute STEP 0

Configuration guide flow (all prompts in Chinese)

📋 Configuration steps

❓ Frequently asked questions

Prompt after a successful connection

🎯 Core feature overview

🏗️ Recommended Vault structure (PARA + Zettelkasten)

⚠️ Three hard rules for AI writing

Rule 1: AI-specific landing zone

Rule 2: Append-only writing

Rule 3: Properties whitelist

📋 Feature 1: /daily - Intelligent journal assistant

Trigger conditions

Execution flow

Diary Template Structure

Usage Example

📋 Feature 2: /capture - Quick Knowledge Capture

Trigger Conditions

Execution Flow

Capture Content Format

Usage Example

📋 Feature 3: /review - Periodic Review Generator

Trigger Conditions

Execution Flow

Weekly Review Template

🔧 Configuration Options

🛠️ Technical Implementation

Dependent MCP Tools

Error Handling Strategy

📚 Quick Reference

🆘 Help Command