<div align="center">

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

</div>

---

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, AddTask
│       ├── weekly/          # WeeklySummary, CreateWeekly
│       ├── search/          # VaultSearch, ReadNote, ListNotes
│       └── projects/        # ListProjects, CreateProject
│
├── infrastructure/          # Concrete implementations
│   ├── vault/               # File system operations (fs/promises)
│   ├── parser/              # Markdown + frontmatter parsing (gray-matter)
│   ├── template/            # Templater syntax replacement (dayjs)
│   ├── logging/             # stderr JSON logger (stdout reserved for MCP)
│   └── mcp/                 # MCP server, handlers, presenter, tool definitions
│
└── config/                  # Vault configuration module

Ports & Adapters

Port	Symbol	Implementation
VaultRepository	VAULT_REPOSITORY	FsVaultRepository — File system operations with path traversal protection
NoteParser	NOTE_PARSER	MarkdownNoteParserService — gray-matter + regex parsing
TemplateEngine	TEMPLATE_ENGINE	SimpleTemplateEngineService — Templater syntax with dayjs
LoggerPort	LOGGER_PORT	StderrLoggerService — JSON logs to stderr

---

Configuration

Environment Variables

Variable	Description	Default
VAULT_PATH	Absolute path to Obsidian vault	(required)
DAILY_FOLDER	Daily notes folder	07-Daily
INBOX_FILE	Inbox markdown file	01-Inbox/Inbox.md
PROJECTS_FOLDER	Projects folder	02-Proyectos
AREAS_FOLDER	Areas (PARA) folder	04-Areas
TEMPLATES_FOLDER	Templates folder	Templates
ARCHIVE_FOLDER	Archive folder	06-Archive

Copy .env.example to .env and adjust paths:

cp .env.example .env

Transport Modes

# stdio (default) — for Claude Code / Claude Desktop
node dist/main.js

# SSE — for web clients
node dist/main.js --sse
# Runs on PORT (default: 3000)

---

Vault Structure

Expected Obsidian vault layout:

Vault/
├── 00-Dashboard/          # Central hub with Dataview queries
├── 01-Inbox/
│   └── Inbox.md           # GTD inbox with priority sections
├── 02-Proyectos/          # Active projects with frontmatter
├── 04-Areas/              # PARA areas (Salud, Carrera, Finanzas, etc.)
├── 06-Archive/            # Archived items
├── 07-Daily/              # Daily notes (YYYY-MM-DD.md)
└── Templates/             # Templater templates
    ├── Daily Template.md
    ├── Weekly Review.md
    └── Proyecto Template.md

Inbox Format

## Captura Rápida
- [ ] Some task _2025-01-15 10:30_
- Some note _2025-01-15 11:00_

## Urgente (hacer esta semana)
- [ ] Important task _2025-01-15 09:00_

## Puede esperar
## Algún día / Quizás
## Notas Rápidas

Project Frontmatter

---
estado: En progreso
area: Carrera
inicio: 2025-01-01
deadline: 2025-03-01
objetivo: Build the thing
---

---

Tech Stack

Runtime          Node.js 18+
Framework        NestJS 11 (application context, no HTTP)
MCP SDK          @modelcontextprotocol/sdk 1.12
Parsing          gray-matter (YAML), regex (tasks, sections)
Dates            dayjs (Templater replacement)
Validation       Zod (tool input schemas)
Architecture     Clean Architecture, Ports & Adapters

---

Scripts

Script	Description
npm run build	Compile TypeScript
npm run start:stdio	Run MCP server (stdio)
npm run start:sse	Run MCP server (SSE)
npm run inspect	Open MCP Inspector
npm test	Run tests
npm run test:cov	Run tests with coverage
npm run lint	Lint and fix

---

License

MIT