┌─────────────────────────────────────────────────────────┐
│                 Obsidian Vault (iCloud)                  │
│  ├── Notes/*.md                                          │
│  └── .obsidian-search/semantic-search.db  ← vectors      │
└─────────────────────────────────────────────────────────┘
                    ▲ reads / writes
                    │
┌───────────────────┴─────────────────────────────────────┐
│             Python Backend  (local process)              │
│  FastMCP  stdio   ◄─── Claude Desktop / LLMs             │
│  FastAPI  :51234  ◄─── local scripts (optional)          │
│                                                          │
│  bge-small-en-v1.5  (sentence-transformers, CPU)         │
│  file watcher — incremental reindex on save              │
└──────────────────────────────────────────────────────────┘

Obsidian edits notes on disk; the watcher picks the changes up. Nothing is
installed into Obsidian itself.

obsidian-mcp/
├── packages/
│   └── backend/                  # Python — FastMCP + FastAPI server
│       └── src/obsidian_search/
│           ├── config.py         # pydantic-settings (VAULT_PATH, port, …)
│           ├── models.py         # Chunk, SearchResult, WriteResult, …
│           ├── ingestion/        # chunker_markdown, chunker_pdf, chunker_web
│           ├── embedding/        # embedding model singleton
│           ├── store/            # sqlite-vec CRUD + ANN search
│           ├── search/           # searcher + optional cross-encoder reranker
│           ├── vault/            # note writes (create / append)
│           ├── watcher/          # watchdog FSEventsObserver
│           ├── api/              # FastAPI routes (/search, /ingest/*, /status)
│           └── mcp/              # FastMCP tools for Claude
├── docs/
│   ├── userflows.md              # Mermaid diagrams for all user flows
│   └── branch-protection.md      # GitHub branch protection setup guide
├── .github/workflows/ci.yml      # Lint + typecheck + tests gate
└── PLAN.md                       # Architecture decisions and implementation plan

git clone https://github.com/unnitin/obsidian-mcp.git
cd obsidian-mcp
uv sync --all-extras

cp .env.example .env
# Edit .env and set VAULT_PATH to the absolute path of your Obsidian vault

ls "$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/"

VAULT_PATH=/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVaultName

./scripts/start-backend.sh

ls "$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/"

/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVaultName

sudo pmset -c sleep 0 disksleep 0

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.obsidian-search.backend</string>

  <key>ProgramArguments</key>
  <array>
    <string>/Users/yourname/.local/bin/uv</string>
    <string>run</string>
    <string>--project</string>
    <string>/Users/yourname/obsidian-mcp/packages/backend</string>
    <string>obsidian-search-api</string>
  </array>

  <key>EnvironmentVariables</key>
  <dict>
    <key>VAULT_PATH</key>
    <string>/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVaultName</string>
    <key>HOME</key>
    <string>/Users/yourname</string>
    <key>OBSIDIAN_SEARCH_HOST</key>
    <string>0.0.0.0</string>
    <!-- Required: listening beyond loopback without a token would expose note
         contents and file indexing to the whole network, so the server exits
         at startup if this is missing. Generate one with:
         python -c 'import secrets; print(secrets.token_urlsafe(32))' -->
    <key>OBSIDIAN_SEARCH_API_TOKEN</key>
    <string>paste-your-generated-token-here</string>
  </dict>

  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>

  <key>StandardOutPath</key>
  <string>/tmp/obsidian-search.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/obsidian-search.err</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.obsidian-search.backend.plist

launchctl list | grep obsidian-search
curl http://localhost:51234/health
tail -f /tmp/obsidian-search.log

python -c 'import secrets; print(secrets.token_urlsafe(32))'
# put the result in OBSIDIAN_SEARCH_API_TOKEN, then send it on every request:
curl -H "Authorization: Bearer $TOKEN" http://192.168.1.42:51234/status

# Find the Mac mini's IP
# On the Mac mini:
ipconfig getifaddr en0

# Reach it from your other Mac at:
# http://192.168.x.x:51234

{
  "mcpServers": {
    "obsidian-search": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/obsidian-mcp/packages/backend",
        "python", "-m", "obsidian_search.mcp.server"
      ],
      "env": {
        "VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

"What did I write about the CAP theorem?"
"Summarise my notes on async Rust"
"Index this article for me: https://..."
"Start a note in Projects/ for the migration plan"
"Add today's standup notes to my weekly log"
"How many documents are in my vault index?"

uv run pytest packages/backend/tests/ -v

uv run pytest packages/backend/tests/ --cov=packages/backend/src --cov-report=term-missing

uv run ruff check packages/backend/
uv run ruff format packages/backend/

uv run mypy packages/backend/src/