Installation

Installation

obsidian-tc ships as an npm package, a container image, and a standalone binary. Pick the install path that matches your deployment — see Deployment Modes for the trade-offs.

Requirements

Component	Requirement	Notes
Obsidian	Any recent version	The vault host. Always required.
Local REST API plugin	coddingtonbear/obsidian-local-rest-api	HTTP entry point into the vault. Required for all vault I/O.
Companion plugin	obsidian-tc (this project)	Required for the command palette and any plugin-bridge tool. See Plugin Bridges.
Node	>= 24 LTS	The server test runner uses node:sqlite.
Bun	>= 1.1.0 (CI pins 1.3.x)	Runtime for the server.

The Rust toolchain is only needed if you build the native module yourself. Every native export has a numerically identical pure-JS fallback, so a missing prebuild never blocks you.

Install via npm (recommended)

npm install -g obsidian-tc
obsidian-tc serve --vault /path/to/vault

The install pulls a prebuilt native module for your platform from optionalDependencies. Eight triples ship:

@the-40-thieves/obsidian-tc-native-linux-x64-gnu
@the-40-thieves/obsidian-tc-native-linux-arm64-gnu
@the-40-thieves/obsidian-tc-native-linux-x64-musl
@the-40-thieves/obsidian-tc-native-linux-arm64-musl
@the-40-thieves/obsidian-tc-native-darwin-x64
@the-40-thieves/obsidian-tc-native-darwin-arm64
@the-40-thieves/obsidian-tc-native-win32-x64-msvc
@the-40-thieves/obsidian-tc-native-win32-arm64-msvc

Any platform without a prebuild (or with OBSIDIAN_TC_FORCE_JS_FALLBACK=1) uses the pure-JS fallback automatically.

Install via Docker

docker run -v /path/to/vault:/vault \
  ghcr.io/the-40-thieves/obsidian-tc:1.3.3 serve --http

The native module is prebuilt into the image. The vault is bind-mounted; your Obsidian (with the companion + Local REST API plugins) runs on the host, not in the container. On Linux use --network host so the container can reach Obsidian's REST API plugin; on macOS/Windows map the port explicitly.

Standalone binary

Download the platform binary from GitHub Releases. No Bun install required — the runtime and native module are statically linked (~80 MB per platform).

./obsidian-tc serve --vault /path/to/vault

Install the companion plugin

1. Install and enable Local REST API in Obsidian (Community Plugins). Copy its API key from the plugin settings.
2. Install and enable the obsidian-tc companion plugin. It registers /obsidian-tc/v1/* routes on the REST API plugin's port (default 127.0.0.1:27124).
3. Mirror the REST API key into your config (vaults[].restApiKey) — see Configuration.

Direct file operations (read_note, write_note, etc.) work through the Local REST API plugin alone. Plugin-bridge tools (Dataview, Tasks, Templater, OCR, …) additionally require the companion plugin and the specific third-party plugin — a missing link returns plugin_missing naming the plugin. See the dependency chain in Plugin Bridges.

Connect an MCP client

STDIO (Claude Desktop / Claude Code):

{
  "mcpServers": {
    "obsidian-tc": {
      "command": "obsidian-tc",
      "args": ["serve", "--stdio"],
      "env": { "OBSIDIAN_TC_CONFIG": "/path/to/config.json" }
    }
  }
}

HTTP local:

obsidian-tc serve --http --port 8765

Connect clients to http://127.0.0.1:8765. An unauthenticated server refuses to bind a non-loopback host — remote exposure requires JWT (see Security and ACL).

Verify the install

Call the server_health tool. It round-trips the full transport → auth → ACL → audit path and returns liveness plus build info. list_vaults confirms your vault registry loaded.

Build from source

git clone https://github.com/the-40-thieves/obsidian-tc.git
cd obsidian-tc
bun install        # native falls back to pure-JS if Rust is absent
bun run build
bun run test

Full dev setup is in Contributing.