PluginBench
MCP Server

Obsidian Brain MCP Server

io.github.sweir1/obsidian-brain

RepositoryRegistry

What is the Obsidian Brain MCP server?

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

How to install Obsidian Brain

Copy-paste configuration for popular MCP clients.

transport: stdio
Config generated by PluginBench — verify against the source before use.
Environment / auth
  • VAULT_PATH
    required

    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.

Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-brain",
        "-y",
        "server"
      ],
      "env": {
        "VAULT_PATH": "<YOUR_VAULT_PATH>",
        "DATA_DIR": "<YOUR_DATA_DIR>",
        "EMBEDDING_PRESET": "<YOUR_EMBEDDING_PRESET>",
        "EMBEDDING_MODEL": "<YOUR_EMBEDDING_MODEL>",
        "EMBEDDING_PROVIDER": "<YOUR_EMBEDDING_PROVIDER>",
        "OLLAMA_BASE_URL": "<YOUR_OLLAMA_BASE_URL>",
        "OLLAMA_EMBEDDING_DIM": "<YOUR_OLLAMA_EMBEDDING_DIM>",
        "OLLAMA_NUM_CTX": "<YOUR_OLLAMA_NUM_CTX>",
        "OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL": "<YOUR_OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL>",
        "OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL": "<YOUR_OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL>",
        "OBSIDIAN_BRAIN_NO_WATCH": "<YOUR_OBSIDIAN_BRAIN_NO_WATCH>",
        "OBSIDIAN_BRAIN_NO_CATCHUP": "<YOUR_OBSIDIAN_BRAIN_NO_CATCHUP>",
        "OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS": "<YOUR_OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS>",
        "OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS": "<YOUR_OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS>",
        "OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS": "<YOUR_OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS>",
        "OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS": "<YOUR_OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS>",
        "OBSIDIAN_BRAIN_CONFIG_DIR": "<YOUR_OBSIDIAN_BRAIN_CONFIG_DIR>",
        "OBSIDIAN_BRAIN_DEBUG": "<YOUR_OBSIDIAN_BRAIN_DEBUG>",
        "OBSIDIAN_BRAIN_LOG_FORMAT": "<YOUR_OBSIDIAN_BRAIN_LOG_FORMAT>"
      }
    }
  }
}
Cursor
~/.cursor/mcp.json
{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-brain",
        "-y",
        "server"
      ],
      "env": {
        "VAULT_PATH": "<YOUR_VAULT_PATH>",
        "DATA_DIR": "<YOUR_DATA_DIR>",
        "EMBEDDING_PRESET": "<YOUR_EMBEDDING_PRESET>",
        "EMBEDDING_MODEL": "<YOUR_EMBEDDING_MODEL>",
        "EMBEDDING_PROVIDER": "<YOUR_EMBEDDING_PROVIDER>",
        "OLLAMA_BASE_URL": "<YOUR_OLLAMA_BASE_URL>",
        "OLLAMA_EMBEDDING_DIM": "<YOUR_OLLAMA_EMBEDDING_DIM>",
        "OLLAMA_NUM_CTX": "<YOUR_OLLAMA_NUM_CTX>",
        "OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL": "<YOUR_OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL>",
        "OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL": "<YOUR_OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL>",
        "OBSIDIAN_BRAIN_NO_WATCH": "<YOUR_OBSIDIAN_BRAIN_NO_WATCH>",
        "OBSIDIAN_BRAIN_NO_CATCHUP": "<YOUR_OBSIDIAN_BRAIN_NO_CATCHUP>",
        "OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS": "<YOUR_OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS>",
        "OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS": "<YOUR_OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS>",
        "OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS": "<YOUR_OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS>",
        "OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS": "<YOUR_OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS>",
        "OBSIDIAN_BRAIN_CONFIG_DIR": "<YOUR_OBSIDIAN_BRAIN_CONFIG_DIR>",
        "OBSIDIAN_BRAIN_DEBUG": "<YOUR_OBSIDIAN_BRAIN_DEBUG>",
        "OBSIDIAN_BRAIN_LOG_FORMAT": "<YOUR_OBSIDIAN_BRAIN_LOG_FORMAT>"
      }
    }
  }
}
Windsurf
~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-brain",
        "-y",
        "server"
      ],
      "env": {
        "VAULT_PATH": "<YOUR_VAULT_PATH>",
        "DATA_DIR": "<YOUR_DATA_DIR>",
        "EMBEDDING_PRESET": "<YOUR_EMBEDDING_PRESET>",
        "EMBEDDING_MODEL": "<YOUR_EMBEDDING_MODEL>",
        "EMBEDDING_PROVIDER": "<YOUR_EMBEDDING_PROVIDER>",
        "OLLAMA_BASE_URL": "<YOUR_OLLAMA_BASE_URL>",
        "OLLAMA_EMBEDDING_DIM": "<YOUR_OLLAMA_EMBEDDING_DIM>",
        "OLLAMA_NUM_CTX": "<YOUR_OLLAMA_NUM_CTX>",
        "OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL": "<YOUR_OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL>",
        "OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL": "<YOUR_OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL>",
        "OBSIDIAN_BRAIN_NO_WATCH": "<YOUR_OBSIDIAN_BRAIN_NO_WATCH>",
        "OBSIDIAN_BRAIN_NO_CATCHUP": "<YOUR_OBSIDIAN_BRAIN_NO_CATCHUP>",
        "OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS": "<YOUR_OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS>",
        "OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS": "<YOUR_OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS>",
        "OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS": "<YOUR_OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS>",
        "OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS": "<YOUR_OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS>",
        "OBSIDIAN_BRAIN_CONFIG_DIR": "<YOUR_OBSIDIAN_BRAIN_CONFIG_DIR>",
        "OBSIDIAN_BRAIN_DEBUG": "<YOUR_OBSIDIAN_BRAIN_DEBUG>",
        "OBSIDIAN_BRAIN_LOG_FORMAT": "<YOUR_OBSIDIAN_BRAIN_LOG_FORMAT>"
      }
    }
  }
}
VS Code
.vscode/mcp.json
{
  "servers": {
    "obsidian-brain": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "obsidian-brain",
        "-y",
        "server"
      ],
      "env": {
        "VAULT_PATH": "<YOUR_VAULT_PATH>",
        "DATA_DIR": "<YOUR_DATA_DIR>",
        "EMBEDDING_PRESET": "<YOUR_EMBEDDING_PRESET>",
        "EMBEDDING_MODEL": "<YOUR_EMBEDDING_MODEL>",
        "EMBEDDING_PROVIDER": "<YOUR_EMBEDDING_PROVIDER>",
        "OLLAMA_BASE_URL": "<YOUR_OLLAMA_BASE_URL>",
        "OLLAMA_EMBEDDING_DIM": "<YOUR_OLLAMA_EMBEDDING_DIM>",
        "OLLAMA_NUM_CTX": "<YOUR_OLLAMA_NUM_CTX>",
        "OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL": "<YOUR_OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL>",
        "OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL": "<YOUR_OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL>",
        "OBSIDIAN_BRAIN_NO_WATCH": "<YOUR_OBSIDIAN_BRAIN_NO_WATCH>",
        "OBSIDIAN_BRAIN_NO_CATCHUP": "<YOUR_OBSIDIAN_BRAIN_NO_CATCHUP>",
        "OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS": "<YOUR_OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS>",
        "OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS": "<YOUR_OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS>",
        "OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS": "<YOUR_OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS>",
        "OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS": "<YOUR_OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS>",
        "OBSIDIAN_BRAIN_CONFIG_DIR": "<YOUR_OBSIDIAN_BRAIN_CONFIG_DIR>",
        "OBSIDIAN_BRAIN_DEBUG": "<YOUR_OBSIDIAN_BRAIN_DEBUG>",
        "OBSIDIAN_BRAIN_LOG_FORMAT": "<YOUR_OBSIDIAN_BRAIN_LOG_FORMAT>"
      }
    }
  }
}
Claude Code
claude mcp add obsidian-brain --env VAULT_PATH=<YOUR_VAULT_PATH> --env DATA_DIR=<YOUR_DATA_DIR> --env EMBEDDING_PRESET=<YOUR_EMBEDDING_PRESET> --env EMBEDDING_MODEL=<YOUR_EMBEDDING_MODEL> --env EMBEDDING_PROVIDER=<YOUR_EMBEDDING_PROVIDER> --env OLLAMA_BASE_URL=<YOUR_OLLAMA_BASE_URL> --env OLLAMA_EMBEDDING_DIM=<YOUR_OLLAMA_EMBEDDING_DIM> --env OLLAMA_NUM_CTX=<YOUR_OLLAMA_NUM_CTX> --env OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL=<YOUR_OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL> --env OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL=<YOUR_OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL> --env OBSIDIAN_BRAIN_NO_WATCH=<YOUR_OBSIDIAN_BRAIN_NO_WATCH> --env OBSIDIAN_BRAIN_NO_CATCHUP=<YOUR_OBSIDIAN_BRAIN_NO_CATCHUP> --env OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS=<YOUR_OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS> --env OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS=<YOUR_OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS> --env OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS=<YOUR_OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS> --env OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS=<YOUR_OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS> --env OBSIDIAN_BRAIN_CONFIG_DIR=<YOUR_OBSIDIAN_BRAIN_CONFIG_DIR> --env OBSIDIAN_BRAIN_DEBUG=<YOUR_OBSIDIAN_BRAIN_DEBUG> --env OBSIDIAN_BRAIN_LOG_FORMAT=<YOUR_OBSIDIAN_BRAIN_LOG_FORMAT> -- npx -y obsidian-brain -y server

Related MCP servers

Scrapling MCP Server

Active

Give your AI agent stealth web scraping with Cloudflare bypass and CSS selection, powered by Scrapling.

67k
Python
BSD-3-Clause
View repository →

Chrome DevTools MCP

Active

Give your AI coding agent full control of a live Chrome browser for automation, debugging, and performance analysis.

45k
TypeScript
Apache-2.0
View repository →

com.puter/mcp-server

Active

Let AI agents manage your Puter files, websites, and serverless workers over MCP.

43k
TypeScript
AGPL-3.0
View repository →

io.github.bytedance/mcp-server-browser

Active

Browser automation for AI agents via MCP, powering ByteDance's Agent TARS hybrid GUI/DOM browser control.

37k
TypeScript
Apache-2.0
View repository →

io.github.bytedance/mcp-server-commands

Active

Run arbitrary shell commands from an MCP-connected AI agent.

37k
TypeScript
Apache-2.0
View repository →

io.github.bytedance/mcp-server-filesystem

Active

Filesystem access MCP server from ByteDance's UI-TARS/Agent TARS ecosystem.

37k
TypeScript
Apache-2.0
View repository →