obsidian-mcp

A TypeScript MCP server that exposes your Obsidian vault to any MCP-compatible client (Claude Desktop, Claude Code, etc.) with full-text + semantic search and Anki-style spaced-repetition active recall.

---

Features

Capability	Tools
Vault reading	list_notes, get_note, get_recent_notes, get_backlinks, get_vault_stats
Search	search_notes (hybrid FTS5 + semantic), get_notes_by_topic
Active recall	cross_question, get_due_questions, submit_review, get_topic_mastery
Question store	add_questions, list_questions, delete_question

• Local embeddings — all-MiniLM-L6-v2 via @xenova/transformers. No note content leaves the machine.
• SQLite — FTS5 full-text index + embedding vectors (pure-JS cosine similarity fallback if sqlite-vec is unavailable).
• Git sync — vault mirrored from MacBook → EC2 via git; health status reported in get_vault_stats.
• SM-2 scheduler — classic SuperMemo-2 algorithm for spaced repetition.
• stdio + HTTP/SSE transports — stdio for Claude Desktop, SSE for remote EC2 access.

---

Quick Start (local / Claude Desktop)

# 1. Clone and install
git clone https://github.com/YOUR_USERNAME/obsidian-mcp.git
cd obsidian-mcp
npm install

# If on Node 25+ (no prebuilt better-sqlite3 binary yet), build from source:
npm run rebuild:sqlite

# 2. Build
npm run build

# 3. Copy and edit .env
cp .env.example .env
# Set VAULT_PATH to your Obsidian vault directory

# 4. Run (stdio mode)
VAULT_PATH=/path/to/your/vault npm start

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

---

Environment Variables

Variable	Required	Default	Description
VAULT_PATH	✅	—	Absolute path to Obsidian vault
TRANSPORT	No	stdio	stdio or http
PORT	No	3000	HTTP port (when TRANSPORT=http)
MCP_AUTH_TOKEN	No*	—	Bearer token for HTTP auth (*required in production)
DB_PATH	No	./data/obsidian-mcp.db	SQLite database path
LOG_LEVEL	No	info	debug | info | warn | error
TRANSFORMERS_CACHE	No	~/.cache/huggingface	Where to cache the embedding model

---

EC2 Deployment

1. Set up EC2 → GitHub SSH access

# On EC2: generate a deploy key (read-only) for the vault repo
ssh-keygen -t ed25519 -C "ec2-vault-deploy" -f ~/.ssh/vault_deploy_key -N ""
cat ~/.ssh/vault_deploy_key.pub
# Add the public key to your vault repo as a read-only deploy key on GitHub

2. Run the bootstrap script

# On EC2 (as ec2-user):
export REPO_URL="https://github.com/YOUR_USERNAME/obsidian-mcp.git"
export VAULT_REPO="git@github.com:YOUR_USERNAME/obsidian-vault.git"
bash scripts/setup-ec2.sh

The script:

• Installs Node.js 20 via nvm
• Clones vault + server repos
• Builds TypeScript
• Creates .env with a randomly generated MCP_AUTH_TOKEN
• Installs and starts all systemd units (MCP server + 5-min vault sync timer)

3. Set up nginx + TLS

sudo apt install -y nginx certbot python3-certbot-nginx

# Copy config and replace domain
sudo cp nginx/obsidian-mcp.conf /etc/nginx/sites-available/obsidian-mcp
sudo ln -s /etc/nginx/sites-available/obsidian-mcp /etc/nginx/sites-enabled/
# Edit: sed -i 's/mcp.yourdomain.com/your.actual.domain/g' /etc/nginx/sites-available/obsidian-mcp

sudo certbot --nginx -d your.actual.domain
sudo systemctl reload nginx

4. Mac → EC2 vault sync (auto git push)

# Edit VAULT_DIR in the plist first
nano launchd/com.obsidian.sync.plist

# Install
cp launchd/com.obsidian.sync.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.obsidian.sync.plist

# Verify
launchctl list | grep obsidian
tail -f /tmp/obsidian-sync.log

5. Claude Desktop → EC2 (HTTP/SSE)

{
  "mcpServers": {
    "obsidian-remote": {
      "url": "https://your.actual.domain/sse",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
      }
    }
  }
}

---

Active Recall Workflow

User: "Quiz me on machine learning"
  → cross_question(topic="machine learning", depth="medium")
  ← Server returns: relevant notes + due questions

Claude reads notes, asks due questions first, then generates new ones
  → submit_review(question_id=42, grade="good")
  ← SM-2 schedules next review in N days

  → add_questions(note_path="ML/Backprop.md", questions=[...])
  ← Stored for future review sessions

User: "How am I doing on ML?"
  → get_topic_mastery(topic="machine learning")
  ← Stats: 23 questions, 18 reviewed, avg ease 2.3, 3 weak areas

---

MCP Tools Reference

Vault Tools

Tool	Description
list_notes	List notes, filter by tag and/or folder
get_note	Get full note content by path or title
search_notes	Hybrid FTS + semantic search (mode: hybrid/fulltext/semantic)
get_notes_by_topic	Semantic + tag search for a topic
get_backlinks	Find notes linking to a note via [[wikilinks]]
get_recent_notes	N most recently modified notes
get_vault_stats	Note count, tags, folders, git sync status

Review Tools

Tool	Description
cross_question	Quiz-me entry point: returns notes + due questions for a topic
get_due_questions	Questions due for review today (SM-2 scheduled)
submit_review	Record grade (again/hard/good/easy), update SM-2 schedule
get_topic_mastery	Aggregate stats: reviewed, overdue, avg ease, weak areas

Question Tools

Tool	Description
add_questions	Store LLM-generated questions for a note
list_questions	List all questions, filtered by note path
delete_question	Remove a question from the review queue

---

Architecture

obsidian-mcp/
├── src/
│   ├── index.ts              # Entry point (stdio / HTTP)
│   ├── server.ts             # McpServer factory
│   ├── db/
│   │   ├── schema.ts         # SQLite init (FTS5, embeddings, SM-2 state)
│   │   └── sm2.ts            # SM-2 algorithm
│   ├── embeddings/
│   │   └── model.ts          # @xenova/transformers wrapper + cosine fallback
│   ├── vault/
│   │   ├── parser.ts         # Markdown → Note (gray-matter, wikilinks, tags)
│   │   ├── indexer.ts        # Full scan + chokidar file watcher
│   │   └── search.ts         # FTS5 + semantic + hybrid + topic search
│   ├── tools/
│   │   ├── vault.ts          # Vault reading tools
│   │   ├── questions.ts      # Question CRUD tools
│   │   └── review.ts         # Active recall + SM-2 tools
│   └── transport/
│       └── http.ts           # Express SSE + bearer auth
├── systemd/                  # EC2 systemd units + timer
├── launchd/                  # Mac launchd plist (auto git push)
├── nginx/                    # nginx reverse proxy config
└── scripts/
    └── setup-ec2.sh          # EC2 one-shot bootstrap

---

Notes on sqlite-vec

The server automatically attempts to load the sqlite-vec native extension for vector operations. If it fails to load (e.g. on some Apple Silicon configs without Rosetta), it falls back seamlessly to a pure-JS cosine similarity implementation. This fallback works well for vaults up to ~5,000 notes; for larger vaults, ensure sqlite-vec is available.

# Test if sqlite-vec loads on your system
node -e "require('sqlite-vec')"

---

Backups

The SQLite DB (data/obsidian-mcp.db) holds your review state — this is the only data that can't be reconstructed from the vault. Back it up:

# Manual backup
cp data/obsidian-mcp.db "data/obsidian-mcp-$(date +%Y%m%d).db"

# Cron backup on EC2 (add to crontab)
0 3 * * * sqlite3 /home/ec2-user/obsidian-mcp/data/obsidian-mcp.db ".backup '/home/ec2-user/backups/obsidian-mcp-$(date +\%Y\%m\%d).db'"

---

License

MIT