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.