Skip to main content
Glama
Sign In
mcp-obsidian-planner

mcp-obsidian-planner

by jarero321
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

Related MCP server: Enhanced Obsidian MCP Server

Getting Started

Prerequisites

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

Available Tools

17 tools
daily_createA

Create a daily note from template. Returns existing note if already created.

Inputs: date.

daily_getC

Get a daily note with parsed sections (focus, tasks, log, gratitude, reflection)

Inputs: date.

daily_set_focusC

Set the Top 3 focus priorities for a daily note

Inputs: focus (required), date.

inbox_addC

Add a new item to the inbox with timestamp

Inputs: text (required), isTask, priority.

inbox_listB

List all inbox items grouped by priority (Urgente, Puede esperar, Algún día, Captura Rápida, Notas Rápidas)

Inputs: no named parameters.

inbox_prioritizeC

Change the priority of an inbox item by moving it to a different section

Inputs: lineNumber (required), newPriority (required).

inbox_processB

Process an inbox item by moving it to a project, daily note, area, archive, or deleting it

Inputs: lineNumber (required), destination (required), targetPath.

note_readB

Read a note from the vault by its relative path

Inputs: path (required).

notes_listB

List all notes in a folder

Inputs: folder (required), pattern.

project_createC

Create a new project from template with area assignment

Inputs: name (required), area (required).

projects_listB

List projects with status, area, deadline. Filter by status or area.

Inputs: status, area.

task_addC

Add a new task to a note in the Tareas section

Inputs: path (required), text (required), section.

tasks_listB

List tasks from a specific note, folder, or the entire vault. Filter by status.

Inputs: path, folder, status.

task_toggleB

Toggle a task between pending [ ] and completed [x]

Inputs: sourcePath (required), lineNumber (required).

vault_searchC

Full-text search across the vault with context lines

Inputs: query (required), folder, limit.

weekly_createC

Create a weekly review note from template

Inputs: date.

weekly_summaryB

Generate weekly summary: completed/pending tasks, dailies filled, project progress

Inputs: date.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.6/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity. For example, daily_create, daily_get, and daily_set_focus all target different operations on daily notes, while inbox_add, inbox_list, inbox_prioritize, and inbox_process handle distinct inbox management steps. The tool set avoids overlap, making it easy for an agent to select the correct tool.

    Naming Consistency5/5

    Tool names follow a consistent verb_noun pattern throughout, such as daily_create, inbox_add, note_read, and project_create. All tools use snake_case with clear, descriptive names that indicate both the resource and action, providing a predictable and readable naming convention across the entire set.

    Tool Count5/5

    With 17 tools, the count is well-scoped for a planner application covering daily notes, inbox management, projects, tasks, and vault operations. Each tool earns its place by addressing specific needs in the domain, such as creating, reading, listing, and updating various elements, without being excessive or insufficient for the server's purpose.

    Completeness5/5

    The tool set provides complete CRUD/lifecycle coverage for the planner domain, including creation (e.g., daily_create, project_create), reading (e.g., daily_get, note_read), updating (e.g., daily_set_focus, task_toggle), and deletion (implied in inbox_process). It covers all core workflows from inbox capture to project management and weekly reviews, with no obvious gaps that would cause agent failures.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • obsidian-ts-mcp

      dickiedyce
      A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that wraps the official Obsidian CLI to allow AI agents to read, write, search, and manage notes within an Obsidian vault. It provides 16 specialized tools for comprehensive vault interaction, including note management, task tracking, and metadata manipulation.
      16
      13
      MIT