Obsidian Project Management MCP Server

Obsidian Project Management MCP Server

Current Version: v0.2.21

An MCP (Model Context Protocol) server for AI-native project management in Obsidian. Enables AI assistants to create, update, search, and manage project entities stored as markdown files with automatic relationship tracking.

What This Does

This MCP server lets AI assistants:

• Manage project entities — create, update, and track milestones, stories, tasks, decisions, documents, and features
• Handle dependencies — define relationships between entities with automatic bidirectional sync
• Track progress — see project status, workstream health, and feature coverage
• Navigate hierarchies — traverse parent-child relationships and dependency graphs
• Batch operations — efficient bulk create/update/archive with dry-run preview

┌─────────────────────────────────────────────────────────────────────┐
│                        Your Workflow                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   ┌──────────┐      ┌──────────────┐      ┌──────────┐              │
│   │ Obsidian │◄────►│  MCP Server  │◄────►│    AI    │              │
│   │  Vault   │      │  (this repo) │      │ Assistant│              │
│   └──────────┘      └──────────────┘      └──────────┘              │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Installation

Prerequisites

• Node.js 18 or later
• An Obsidian vault

Configure Your AI Assistant

Add the MCP server to your AI client's configuration. No separate installation needed - npx handles it automatically.

Latest Version: v0.2.21

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@ostanlabs/obsidian-mcp"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/your/obsidian/vault",
        "DEFAULT_CANVAS": "projects/main.canvas"
      }
    }
  }
}

With Semantic Search (optional):

To enable hybrid vector + keyword search, add the --semantic-search flag:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@ostanlabs/obsidian-mcp", "--semantic-search"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/your/obsidian/vault",
        "DEFAULT_CANVAS": "projects/main.canvas"
      }
    }
  }
}

Note: Semantic search requires downloading the BGE-M3 ONNX model (~2.3 GB) on first use. The model is stored at ~/.msrl/models/bge-m3 and only needs to be downloaded once.

Vault Structure

The server will create entities in these folders (create them if they don't exist):

your-vault/
├── milestones/               # M-xxx.md
├── stories/                  # S-xxx.md
├── tasks/                    # T-xxx.md
├── decisions/                # DEC-xxx.md
├── documents/                # DOC-xxx.md
├── features/                 # F-xxx.md
└── archive/                  # Archived entities

Configure Workspaces

Workspaces define document collections that the AI can access. You can configure them in two ways:

Option 1: Ask the AI (recommended)

"Add a workspace called 'docs' pointing to /path/to/my/docs folder""Add a notes workspace for my meeting notes at /path/to/notes"

Option 2: Edit manually

On first run, the server creates a workspaces.json file in your vault:

{
  "docs": {
    "path": "/absolute/path/to/your/vault/docs",
    "description": "Project documentation and reference materials"
  }
}

Core Concepts

Entity Hierarchy

The system uses a hierarchical entity model:

Milestone (M-xxx)
└── Story (S-xxx)
    └── Task (T-xxx)

Feature (F-xxx)     ─── product features with coverage tracking
Decision (DEC-xxx)  ─── captured choices, can affect other entities
Document (DOC-xxx)  ─── specs/ADRs, can be implemented by stories

Entity Types

Entity Status

Relationships (Auto-Synced)

All relationships are bidirectional and automatically synchronized:

Workstreams

Entities are organized by workstream. Values are automatically normalized:

• infrastructure, infra → infra
• eng, engineering → engineering
• biz, business → business
• ops, operations → operations
• r&d, rnd, research → research
• ux, ui, design → design
• mktg, marketing → marketing

MSRL Semantic Search

Search your entire vault using hybrid vector + keyword search.

Requires: Start the server with --semantic-search flag to enable.

Features:

• Hybrid search - Combines vector embeddings with keyword matching
• Auto-download - BGE-M3 model (~2.3 GB) downloaded automatically on first use
• Fast indexing - Automatic index updates on document changes
• Relevance ranking - Results ranked by semantic similarity

Model Storage:The ONNX model is stored at ~/.msrl/models/bge-m3 and shared across all vaults.

Tools (only available with --semantic-search):

• search_docs - Semantic search across workspace documents
• msrl_status - Check semantic search index status
• search_entities with semantic: true - Hybrid search for entities

Example queries:

"Search for all documents about authentication""Find references to database design decisions""Show me documentation about API endpoints"

See Semantic Search Guide for setup and advanced usage.

Archive Structure

Archived entities are organized in a flat structure by type:

archive/
├── milestones/
├── stories/
├── tasks/
├── decisions/
├── documents/
└── features/

Entities with status: archived are automatically moved to the appropriate folder and excluded from canvas and searches.

See Archive Structure Guide for workflows.

Migration Notes

Recent Schema Changes

Decision Relationships:

• ✅ Use affects field (new)
• ❌ blocks field is deprecated

Story Workstreams:

• ✅ Use workstream field (new)
• ❌ effort field is deprecated (auto-migrated)

CSS Classes:

• ✅ Use canvas-workstream-* pattern (new)
• ❌ canvas-effort-* pattern is deprecated

See Entity Schemas for complete schema documentation.

Available Tools

The MCP server provides 27 tools organized by function:

Entity Management

Batch Operations

Project Understanding

Search & Navigation

Document Management

Canvas Operations

Maintenance

Workspace Management

Utility Tools

Usage Examples

Once configured, ask your AI assistant things like:

Project Overview

"What's the status of my project?""Show me the engineering workstream status""What items are blocked?""Analyze the project and identify risks"

Managing Entities

"Create a milestone for Q1 launch with target date March 31""Create a story under M-001 for user authentication""Add a task to S-003 for writing unit tests""Mark T-005 as completed"

Dependencies

"S-004 depends on S-002 and S-003""What's blocking S-006?""Show me the dependency graph for M-001"

Decisions & Documents

"Create a decision about using PostgreSQL vs MongoDB""What decisions have been made about authentication?""Create a spec document for the API design""Is DOC-003 up to date with recent decisions?"

Features

"What's the feature coverage for Phase 2?""Which features are missing documentation?""Show me F-001's implementation status"

Documents

"What workspaces are available?""List files in the docs workspace""Read the architecture document"

Documentation

For comprehensive documentation, see the obsidian_docs repository:

Quick Links

• Quick Start Guide - Get started in 15 minutes
• User Guide - Complete workflows and features
• MCP Tools Reference - All 27 tools documented
• Entity Schemas - Complete entity definitions

Feature Guides

• Semantic Search - MSRL hybrid search
• Feature Coverage - Track implementation status
• Workspace Management - Multi-vault organization
• Relationship Reconciliation - Data integrity
• Archive Structure - Archive workflows
• Workstream Normalization - Auto-normalization

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Type check
npm run typecheck

Project Structure

src/
├── index.ts              # MCP server entry point
├── models/
│   └── v2-types.ts       # Entity type definitions
├── services/v2/
│   ├── entity-parser.ts      # Parse markdown to entities
│   ├── entity-serializer.ts  # Serialize entities to markdown
│   ├── entity-validator.ts   # Validate entity data
│   ├── index-manager.ts      # Entity indexing
│   ├── lifecycle-manager.ts  # Status transitions
│   ├── archive-manager.ts    # Archive/restore
│   ├── workstream-normalizer.ts  # Workstream normalization
│   ├── cycle-detector.ts     # Dependency cycle detection
│   └── v2-runtime.ts         # Main runtime
└── tools/
    ├── index.ts              # Tool definitions
    ├── entity-management-tools.ts
    ├── batch-operations-tools.ts
    ├── project-understanding-tools.ts
    ├── search-navigation-tools.ts
    └── decision-document-tools.ts

License

MIT