mcp-obsidian-second-brain

An MCP (Model Context Protocol) server that gives Claude a persistent, structured memory system backed by an Obsidian vault. Memories are stored as Markdown files with YAML frontmatter using the PARA method (Projects, Areas, Resources, Archives).

Installation

Option 1: npx from GitHub (no clone required)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "obsidian-second-brain": {
      "command": "npx",
      "args": ["-y", "@neverprepared/mcp-obsidian-second-brain"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Option 2: Clone and run locally

git clone https://github.com/neverprepared/mcp-obsidian-second-brain.git
cd mcp-obsidian-second-brain
npm install
npm run build

Then add to your Claude Desktop config:

{
  "mcpServers": {
    "obsidian-second-brain": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-obsidian-second-brain/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Option 3: Claude Code (CLI)

Add to ~/.claude/claude_desktop_config.json or run:

claude mcp add obsidian-second-brain \
  -e OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault \
  -- npx -y @neverprepared/mcp-obsidian-second-brain

Configuration

Environment Variable	Default	Description
OBSIDIAN_VAULT_PATH	~/workspaces/profiles/personal/obsidian/vaults/memory	Path to your Obsidian vault directory
LOG_LEVEL	info	Log verbosity: debug, info, warn, error (logs go to stderr)
MIN_SHARED_TAGS	2	Minimum shared tags required for auto-linking memories

The vault directory will be created automatically on first run with the PARA folder structure.

Tools

Tool	Description
memory_store	Create a new memory in a PARA category with optional tags and source URLs
memory_recall	Fetch a specific memory by ID or title
memory_search	Full-text search with relevance scoring, tag filters (and/or), date filters, and freshness
memory_list	Paginated listing with filters by PARA, tags, status, and date range
memory_update	Update content, tags, PARA category (moves file), or title (renames file)
memory_archive	Set a memory's status to archived
memory_delete	Permanently delete a memory (cascades to clean up backlinks)
memory_link	Create bidirectional [[wiki-links]] between two memories, or discover existing links
memory_project	Create projects with deadlines, mark complete, or list active projects
memory_stats	Vault health summary: counts by PARA/status, stale memories, orphans, top tags
memory_cleanup	Bulk list/archive/delete stale, archived, or orphaned memories (safe dry_run by default)

Vault Structure

<OBSIDIAN_VAULT_PATH>/
├── Projects/     # Time-bound goals (stale after 30 days)
├── Areas/        # Ongoing responsibilities (stale after 90 days)
├── Resources/    # Reference material (stale after 180 days)
├── Archives/     # Inactive memories (stale after 365 days)
└── _daily/       # Daily notes (auto-appended on each store)

Each memory is a Markdown file with YAML frontmatter. Files are named by slugified title and support bidirectional [[wiki-links]].

Development

npm run dev          # Run with tsx (no build required)
npm run build        # Compile TypeScript to dist/
npm run typecheck    # Type-check without emitting
npm test             # Run all tests
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report

Copy .env.example to .env and set OBSIDIAN_VAULT_PATH before running locally.