Obsidian Brain MCP Server

by sweir1io.github.sweir1/obsidian-brainv1.7.24

Obsidian MCP server: semantic search, knowledge graph, and vault editing. No plugin required.

12Node.jsstdioofficial registry

context tax

queued

security

queued

cold start

queued

freshness

Slowing5mo ago

Install Obsidian Brain MCP server

claude mcp add obsidian-brain -e VAULT_PATH='<vault-path>' -- npx -y obsidian-brain server

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-brain",
        "server"
      ],
      "env": {
        "VAULT_PATH": "<vault-path>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-brain",
        "server"
      ],
      "env": {
        "VAULT_PATH": "<vault-path>"
      }
    }
  }
}

Settings → Developer → Edit Config (claude_desktop_config.json), then restart.

{
  "servers": {
    "obsidian-brain": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "obsidian-brain",
        "server"
      ],
      "env": {
        "VAULT_PATH": "<vault-path>"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace.

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-brain",
        "server"
      ],
      "env": {
        "VAULT_PATH": "<vault-path>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json.

Configuration

Variable	Required	Secret	Description
VAULT_PATH	yes	—	Absolute path to your Obsidian vault (or any folder of .md files).
DATA_DIR	—	—	Where to store the SQLite index + embedding cache. Defaults to $XDG_DATA_HOME/obsidian-brain or ~/.local/share/obsidian-brain.
EMBEDDING_PRESET	—	—	Preset name: english (default, bge-small-en-v1.5), english-fast, english-quality, multilingual, multilingual-quality, multilingual-ollama. Ignored when EMBEDDING_MODEL is set.
EMBEDDING_MODEL	—	—	Power-user override: any transformers.js checkpoint or Ollama model id. Takes precedence over EMBEDDING_PRESET. Switching auto-reindexes.
EMBEDDING_PROVIDER	—	—	Embedding backend. 'transformers' (local, default) or 'ollama' (requires a running Ollama server).
OLLAMA_BASE_URL	—	—	Base URL of a local Ollama server. Only used when EMBEDDING_PROVIDER=ollama.
OLLAMA_EMBEDDING_DIM	—	—	Override the embedding dimensionality when EMBEDDING_PROVIDER=ollama. If unset, the server probes the model on startup.
OLLAMA_NUM_CTX	—	—	Override Ollama's num_ctx for embed requests. Leave UNSET to let obsidian-brain auto-detect via `/api/show`'s `context_length` (e.g. nomic-embed-text=2048, bge-m3=8192, qwen3-embedding:0.6b=32 768). Setting this manually imposes a hard cap and may silently truncate longer inputs — see https://github.com/ollama/ollama/issues/14259. Ollama's own default is 2048 which truncates for any model trained on a larger context. See also https://github.com/ollama/ollama/issues/7008. Fallback when both env is unset AND /api/show is unreachable: 8192.
OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL	—	—	Auto-pull the configured Ollama model when /api/show returns 404 (model not present). Default ON — choosing an Ollama-backed preset is implicit consent to download its model. Streams /api/pull progress to stderr. Set to '0' to disable auto-pull entirely (master kill-switch) and fall back to the actionable error path (`HTTP 404 — try: ollama pull <model>`).
OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL	—	—	Opt-in to auto-pull for BYOM (custom EMBEDDING_MODEL) Ollama models OUTSIDE Ollama's official `library/` namespace. Default OFF — third-party models (e.g. `user/custom-fork`, `myregistry.com/team/model`) require this env var to be set to `1` before they will auto-pull, to prevent silent downloads of arbitrary user-named artifacts. Preset-known models (via EMBEDDING_PRESET) and bare model ids in the official library (e.g. `qwen3-embedding:0.6b`, `library/llama3:8b`) continue to auto-pull by default per the existing OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL behavior.
OBSIDIAN_BRAIN_NO_WATCH	—	—	Set to '1' to disable the live chokidar file watcher. Useful on SMB/NFS vaults where FSEvents/inotify don't fire reliably — fall back to running `obsidian-brain index` on a schedule (launchd/systemd).
OBSIDIAN_BRAIN_NO_CATCHUP	—	—	Set to '1' to skip the startup catchup reindex pass that picks up edits made while the server was down. The live file watcher still starts (via OBSIDIAN_BRAIN_NO_WATCH=1 to disable that separately), and first-time indexing on an empty DB is unaffected — this knob only governs the post-restart `enqueueBackgroundReindex` walk.
OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS	—	—	Per-file reindex debounce for the live watcher, in milliseconds.
OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS	—	—	Graph-wide community-detection (Louvain) debounce for the live watcher, in milliseconds. Louvain is the only expensive op — batching it prevents per-edit CPU spikes.
OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS	—	—	Per-tool-call timeout in milliseconds. Tools exceeding this return an MCP error instead of hanging.
OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS	—	—	Override the adaptive chunk-size budget (in tokens). When set, this beats the capacity probed from the model's tokenizer or Ollama /api/show. Use for debugging or for models with stale tokenizer configs.
OBSIDIAN_BRAIN_CONFIG_DIR	—	—	Override the per-user config directory where obsidian-brain stores model overrides (`model-overrides.json`) and the user-fetched seed (`seed-models.json`). Default is `$XDG_CONFIG_HOME/obsidian-brain` on macOS/Linux (or `~/.config/obsidian-brain`) and `%APPDATA%/obsidian-brain` on Windows. Both files survive `npm update obsidian-brain` because they live outside the package.
OBSIDIAN_BRAIN_DEBUG	—	—	Set to "1" to print a verbose synchronous startup trace to stderr — every preflight, createContext, server.connect, and shutdown step is logged with a monotonic timestamp. The LAST line before any silent failure tells you exactly which step the server reached. No-op when unset (no overhead). Use to diagnose silent-crash failure modes.
OBSIDIAN_BRAIN_LOG_FORMAT	—	—	Set to 'ndjson' for one-JSON-object-per-line stderr output (timestamp + level + message + structured fields). Default is human-readable plain text (`obsidian-brain: <message>`). Useful for piping logs into aggregators (Datadog, Loki, Vector, journald) that index structured fields.

Freshness

Slowing — last maintenance signal 5mo ago. The newest of the signals below sets the band.

Last commit (default branch)
2026-05-16 · 5mo ago · GitHub
Latest release
2026-05-16 · 5mo ago · GitHub · v1.7.24
Package published
no data · npm/PyPI
Registry entry updated
2026-05-16 · 5mo ago · official registry · v1.7.24

FAQ

›How do I install the Obsidian Brain MCP server in Claude Code?

Run: claude mcp add obsidian-brain -e VAULT_PATH='<vault-path>' -- npx -y obsidian-brain server. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.

›Does Obsidian Brain require an API key?

Yes. It expects VAULT_PATH.

›Can I use Obsidian Brain as a remote (hosted) MCP server?

No hosted endpoint is published; it runs locally over stdio.

›Is Obsidian Brain in the official MCP registry?

Yes, as io.github.sweir1/obsidian-brain.