Obsidian MCP Server

A Node.js MCP server that gives Claude Code persistent, token-efficient access to any Obsidian vault. Includes hybrid full-text + semantic search and built-in issue tracking.

Prerequisites

• Node.js 18+
• Ollama running locally with nomic-embed-text pulled (optional — server works without it, FTS-only mode)

ollama pull nomic-embed-text

Setup

npm install
npm run build

Register with Claude Code

Add the server to your MCP configuration. Create a .mcp.json file in your project root, or add to ~/.claude/mcp.json for global access:

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

For development, you can use tsx to run TypeScript directly without building:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/obsidian-brain/src/server.ts"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
      }
    }
  }
}

Important:

• Use absolute paths for both the server script and VAULT_PATH
• VAULT_PATH must point to an existing directory — the server will exit immediately if it is missing or invalid
• One server instance per vault

Verify connection

After configuring, restart Claude Code. The server should appear in the MCP tools list. If the connection fails, check:

1. VAULT_PATH is set and points to an existing directory
2. The path to the server script is correct and absolute
3. npm install (and npm run build if using compiled mode) has been run in the obsidian-brain directory
4. Node.js 18+ is available

Tools

Notes

Search

Projects

Issue Tracking

Statuses: backlog, not_started, in_progress, code_review, done, blocked

Priorities: P1 (critical), P2 (high), P3 (medium), P4 (low), P5 (trivial)

Types: bug, feature, task

Vault Structure

The server expects (and works with) this folder layout:

00-inbox/       -- unprocessed captures
01-ideas/       -- raw ideas
02-projects/    -- active projects (each in its own subfolder)
  <project>/
    issues/     -- project-scoped issues
03-research/    -- external knowledge by domain
04-knowledge/   -- refined long-term concepts
05-life/        -- personal planning
06-finance/     -- financial strategy
07-work/        -- professional material
meta/           -- system notes
  issues/       -- global issues (not tied to a project)

How It Works

Search

1. reindex_vault walks all .md files, strips frontmatter, embeds via Ollama, and stores in SQLite (FTS5 + sqlite-vec)
2. search_vault runs keyword (FTS5) and semantic (vector cosine) queries in parallel, merges and deduplicates results
3. Claude calls read_note only on relevant results — this is the token efficiency mechanism

If Ollama is unavailable, the server falls back to FTS5-only search automatically. If sqlite-vec fails to load (e.g. missing native binary), the server falls back to FTS-only mode as well.

Issue Tracking

Issues are dual-stored:

• Markdown note in 02-projects/<project>/issues/ — browsable in Obsidian, includes frontmatter metadata and a notes log. Kept in sync when issues are updated.
• SQLite table in .vault-index.db — enables fast structured queries (filter by status, priority, type, project)

Security

• All note paths are validated to stay within the vault boundary — path traversal attacks (e.g. ../../etc/passwd) are rejected
• FTS5 search input is sanitized to prevent query operator injection

Indexing

Each vault stores its index at <VAULT_PATH>/.vault-index.db. This file is generated and should not be committed to version control.

CLAUDE.md

Place a CLAUDE.md at your vault root with instructions for Claude. It loads automatically each session. Example rules:

• Never delete notes — move to 00-inbox/ if unsure
• Search before creating — avoid duplicate notes
• Use the MCP tools instead of reading/writing files directly
• Respect folder roles

Dependencies