# 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:

   ```text
   <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:

   ```sh
   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.

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

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

   ```sh
   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

```sh
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:

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

Configure an MCP client to use:

```text
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:

```json
{
  "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

```sh
# 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](VERSIONING.md) for the synchronized-version and tag-driven release process, and [CHANGELOG.md](CHANGELOG.md) for release notes.