Which integrations are available for this server?

Enables structured planning within an Obsidian vault using GTD and PARA methodologies, providing tools for managing daily notes, tasks, projects, inbox items, and performing full-text searches.

How do I use mcp-obsidian-planner?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-obsidian-planner Show my top 3 focus items for today and list any urgent inbox tasks." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-obsidian-planner

Version License TypeScript NestJS MCP

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

mcp-obsidian-planner

mcp-obsidian-planner

What It Does

Getting Started

Prerequisites

Installation

Configure Claude Code

Configure Claude Desktop

Verify

Tools

Daily Notes (3)

Inbox (4)

Tasks (3)

Weekly Reviews (2)

Search & Notes (3)

Projects (2)

Architecture

Ports & Adapters

Configuration

Environment Variables

Transport Modes

Vault Structure

Inbox Format

Project Frontmatter

Tech Stack

Scripts

License

Resources

Tools

Latest Blog Posts

MCP directory API