Skip to main content
Glama
jarero321

mcp-obsidian-planner

by jarero321
OverviewSchemaRelated ServersScoreDiscussions
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.

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

Install Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jarero321/mcp-obsidian-planner'

If you have feedback or need assistance with the MCP directory API, please join our Discord server