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, 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