Obsidian MCP Assistant

Desktop-only Obsidian plugin and local companion service for hybrid vault search, cited AI chat, attachment extraction, and read/write MCP access.

Everything indexed and retrieved stays on the machine. Cloud provider requests happen only after a provider, model, and extraction consent are configured. The companion binds to loopback only.

What ships

• Obsidian plugin — assistant pane, hybrid search modal, provider/model settings, extraction consent, MCP token management, rebuild and recovery controls.
• Local companion — the sole owner of index/state SQLite databases, watcher, work queue, retrieval, HTTP control API, and Streamable HTTP MCP endpoint.
• MCP — read, list, links, search, create, edit, move, delete, and reindex tools over either local stdio or authenticated loopback HTTP.
• Retrieval — deterministic BM25/FTS keyword search, optional embeddings, reciprocal-rank hybrid fusion, filters, source provenance, and snapshot-backed chat citations.
• Attachments — local Markdown/Canvas/text/source/office/PDF extraction plus opt-in provider handling for document, image, audio, and video content.

Requirements

• Obsidian desktop 1.11.4 or newer. Mobile is unsupported.
• Node.js 20 or newer for the companion.
• A supported macOS/Linux/Windows native-runtime environment for better-sqlite3, sqlite-vec, @napi-rs/keyring, and sharp.
• Optional provider credentials for OpenAI, Anthropic, and/or Google Gemini. Local keyword indexing does not require a provider.

Install from a release

1. Download the release assets:

   • obsidian-mcp-assistant-plugin-vX.Y.Z.zip
   • obsidian-mcp-companion-X.Y.Z.tgz

2. Extract the plugin zip into your vault at:

   <vault>/.obsidian/plugins/obsidian-mcp-assistant/
   

3. Enable Obsidian MCP Assistant in Obsidian’s Community plugins settings.

4. Install the companion from the tarball in a local directory:

   npm install /path/to/obsidian-mcp-companion-X.Y.Z.tgz
   

5. Register the vault. Save the one-time token printed by this command; it is shown only once.

   npx obsidian-mcp init --vault /absolute/path/to/vault --id my-vault
   

6. Paste that token into the plugin settings, then start the daemon:

   npx obsidian-mcp serve --vault-id my-vault
   

The daemon listens only on 127.0.0.1. Keep it running while using the plugin or MCP clients.

Development install

npm ci
npm run build
npm run dev:install -- /absolute/path/to/vault
node packages/companion/dist/cli.js init --vault /absolute/path/to/vault --id my-vault
node packages/companion/dist/cli.js serve --vault-id my-vault

Run npm run test:native-package before relying on a local native build. It validates the packaged companion and confirms native dependencies are excluded from the Obsidian bundle.

Providers and consent

Provider credentials are validated before persistence and stored by the operating system credential manager, not in plugin data or vault files.

Capability	Supported providers
Chat	OpenAI, Anthropic, Google
Embeddings	OpenAI, Google
Document/image/PDF extraction	OpenAI, Anthropic, Google
Audio extraction	OpenAI, Google
Video extraction	Google

Enable each extraction modality explicitly in the plugin settings. A credential alone does not permit uploads. Extraction failures remain visible as retryable jobs; unsupported/encrypted binaries remain metadata-only rather than being silently omitted.

MCP setup

Streamable HTTP

Create a separately revocable bearer token in plugin settings or with:

npx obsidian-mcp create-mcp-token --vault-id my-vault --name codex

Configure an MCP client to use:

http://127.0.0.1:<port>/mcp
Authorization: Bearer <mcp-token>

Never use the plugin-control token as an MCP bearer token.

Stdio

For local clients that support stdio, configure:

{
  "command": "node",
  "args": [
    "/absolute/path/to/node_modules/@obsidian-mcp/companion/dist/cli.js",
    "stdio",
    "--vault-id",
    "my-vault"
  ]
}

The stdio bridge requires the same vault daemon to be healthy; it never opens the vault databases itself.

Security model

• Loopback-only HTTP; non-loopback peers and unapproved origins are rejected.
• Plugin-control, MCP bearer, and private stdio-bridge credentials are distinct.
• MCP tokens are independently revocable. Revocation closes sessions bound to that token.
• Vault mutations require the current SHA-256 and are journaled with recovery records.
• Traversal, absolute paths, NUL bytes, symlinks, and configured excluded paths are rejected.
• Structured logs redact bodies, note content, tokens, keys, prompts, and provider credentials.

Operations

# Check native runtime support
npx obsidian-mcp doctor

# Persist a provider key; input is read from hidden stdin
npx obsidian-mcp set-key --vault-id my-vault --provider openai

# Remove a provider key
npx obsidian-mcp delete-key --vault-id my-vault --provider openai

# Revoke a single MCP token
npx obsidian-mcp revoke-mcp-token --vault-id my-vault --id <token-id>

Use the plugin settings for rebuilding the index, inspecting jobs, restoring journaled recovery items, rotating the plugin-control token, and session-only provider credentials.

Development commands

Command	Purpose
npm run typecheck	Type-check all workspace packages.
npx tsc -p tsconfig.json --noEmit	Type-check integration tests.
npm run lint	Run strict ESLint checks.
npm run format:check	Verify Prettier formatting.
npm run build	Build companion, contracts, and plugin assets.
npm test	Run the default Vitest suite.
npm run test:integration	Run companion end-to-end tests.
npm run test:native-package	Fresh-install and native dependency verification.

Release and versioning

Releases are GitHub assets, not npm publications. See VERSIONING.md for the synchronized-version and tag-driven release process, and CHANGELOG.md for release notes.