README.md
Obsidian vault planning MCP server with GTD + PARA methodology.
mcp-obsidian-planner
Obsidian vault planning MCP server with GTD + PARA methodology.
17 tools for daily notes, inbox, tasks, projects, weekly reviews and full-text search.
Getting Started · Tools · Architecture · Configuration
What It Does
Connects Claude Code (or any MCP client) directly to your Obsidian vault for structured planning:
- Daily notes — Create from templates, set Top 3 focus, track tasks
- Inbox — Capture ideas, prioritize, process items into projects/areas
- Tasks — List, add, toggle across any note or folder
- Projects — Create with PARA areas, track status and deadlines
- Weekly reviews — Auto-generate summaries with completion rates
- Search — Full-text search across the vault with context
Works with the LifeOS vault structure using Templater templates and Dataview-compatible frontmatter.
Getting Started
Prerequisites
- Node.js >= 18
- An Obsidian vault with folder structure (see Vault Structure)
Installation
git clone https://github.com/jarero321/mcp-obsidian-planner.git
cd mcp-obsidian-planner
npm install
npm run build
Configure Claude Code
Add to ~/.claude/settings.json:
{
"mcpServers": {
"obsidian-planner": {
"command": "node",
"args": ["/path/to/mcp-obsidian-planner/dist/main.js"],
"env": {
"VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
Configure Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"obsidian-planner": {
"command": "node",
"args": ["/path/to/mcp-obsidian-planner/dist/main.js"],
"env": {
"VAULT_PATH": "/path/to/your/obsidian/vault"
}
}
}
}
Verify
# Test with MCP Inspector
npm run inspect
# Or run directly
npm run start:stdio
Tools
Daily Notes (3)
| Tool | Description |
|---|---|
daily_create |
Create a daily note from template. Returns existing note if already created. |
daily_get |
Get a daily note with parsed sections (focus, tasks, log, gratitude, reflection). |
daily_set_focus |
Set the Top 3 focus priorities for a daily note. |
Inbox (4)
| Tool | Description |
|---|---|
inbox_list |
List all inbox items grouped by priority (Urgente, Puede esperar, Algún día, Captura Rápida, Notas Rápidas). |
inbox_add |
Add a new item to the inbox with timestamp. |
inbox_process |
Move an inbox item to a project, daily note, area, archive, or delete it. |
inbox_prioritize |
Change the priority of an inbox item between sections. |
Tasks (3)
| Tool | Description |
|---|---|
tasks_list |
List tasks from a specific note, folder, or the entire vault. Filter by status. |
task_toggle |
Toggle a task between pending [ ] and completed [x]. |
task_add |
Add a new task to a note in a specific section. |
Weekly Reviews (2)
| Tool | Description |
|---|---|
weekly_summary |
Generate weekly summary: completed/pending tasks, dailies filled, project progress. |
weekly_create |
Create a weekly review note from template. |
Search & Notes (3)
| Tool | Description |
|---|---|
vault_search |
Full-text search across the vault with context lines. |
note_read |
Read a note from the vault by its relative path. |
notes_list |
List all notes in a folder with optional pattern filter. |
Projects (2)
| Tool | Description |
|---|---|
projects_list |
List projects with status, area, deadline. Filter by status or area. |
project_create |
Create a new project from template with area assignment. |
Architecture
Clean Architecture with NestJS dependency injection:
src/
├── domain/ # Entities, enums, value objects
│ ├── entities/ # Task, Note, DailyNote, Project, InboxItem, WeeklyReview
│ ├── enums/ # TaskStatus, ProjectStatus, InboxPriority, Area
│ └── value-objects/ # VaultPath (path traversal protection), DateRange
│
├── application/ # Business logic
│ ├── ports/ # Abstractions (VaultRepository, NoteParser, TemplateEngine, Logger)
│ └── use-cases/ # 17 use cases organized by domain
│ ├── daily/ # CreateDaily, GetDaily, SetDailyFocus
│ ├── inbox/ # ListInbox, AddInbox, ProcessInbox, PrioritizeInbox
│ ├── tasks/ # ListTasks, ToggleTask, Ad
Tools (17)
daily_createCreate a daily note from template.daily_getGet a daily note with parsed sections.daily_set_focusSet the Top 3 focus priorities for a daily note.inbox_listList all inbox items grouped by priority.inbox_addAdd a new item to the inbox with timestamp.inbox_processMove an inbox item to a project, daily note, area, archive, or delete it.inbox_prioritizeChange the priority of an inbox item.tasks_listList tasks from a specific note, folder, or the entire vault.task_toggleToggle a task between pending and completed.task_addAdd a new task to a note in a specific section.weekly_summaryGenerate weekly summary of tasks and project progress.weekly_createCreate a weekly review note from template.vault_searchFull-text search across the vault with context lines.note_readRead a note from the vault by its relative path.notes_listList all notes in a folder with optional pattern filter.projects_listList projects with status, area, and deadline.project_createCreate a new project from template with area assignment.Environment Variables
VAULT_PATHrequiredThe absolute file system path to your Obsidian vault.Configuration
claude_desktop_config.json
{"mcpServers": {"obsidian-planner": {"command": "node", "args": ["/path/to/mcp-obsidian-planner/dist/main.js"], "env": {"VAULT_PATH": "/path/to/your/obsidian/vault"}}}}Try it
→Create my daily note for today and set my top 3 focus items to: finish project report, email client, and update budget.
→List all pending tasks in my inbox and move the urgent ones to my active project.
→Search my vault for all notes mentioning 'Q4 strategy' and summarize the findings.
→Generate a weekly review note and include a summary of my completed tasks from the last 7 days.