Obsidian Vault API — Docker

Docker-compatible version of Obsidian Vault API. Exposes your Obsidian vault as an MCP server — no Obsidian desktop app required. Runs 24/7 on any server or NAS.

The original plugin runs inside Obsidian and uses the Obsidian API + Electron's Canvas for image processing. This version runs as a standalone Node.js process in Docker, using direct fs operations and sharp for image resizing. All 13 MCP tools from the original are preserved.

Quick Start

docker-compose (recommended)

services:
  vault-api:
    build: .
    container_name: obsidian-vault-api
    restart: unless-stopped
    ports:
      - "2768:2768"
    volumes:
      - /path/to/your/vault:/vault
      - vault-api-data:/data
    environment:
      - VAULT_API_KEY=your-secret-key-here

volumes:
  vault-api-data:

docker compose up -d

docker run

docker run -d \
  --name obsidian-vault-api \
  -p 2768:2768 \
  -v /path/to/your/vault:/vault \
  -v vault-api-data:/data \
  -e VAULT_API_KEY=your-secret-key-here \
  ghcr.io/alexandre1116/obsidian-vault-api-docker:latest

Web UI

After starting the container, open your browser and go to:

http://localhost:2768/

The dashboard lets you:

• View server status (running/stopped, port, vault name)

• Edit configuration (port, bind address, allowed commands) — changes are saved to /data/config.json and persist across restarts

• Regenerate API key — generates a new secret, requires reconnecting clients

• Restart / Stop the MCP server without stopping the container

• Copy connection info — SSE URL, Claude Desktop JSON config, API key

The web UI itself does not require authentication (it's the config page). The MCP endpoints (/sse, /message, /raw) require the API key.

Configuration

Configuration is stored in /data/config.json and persists across container restarts. Environment variables act as initial overrides on first boot — after that, the config file is the source of truth.

Connecting Your AI Client

LM Studio / Open WebUI / Any MCP client with SSE support

Add MCP server URL:

http://localhost:2768/sse?key=YOUR_API_KEY

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:2768/sse?key=YOUR_API_KEY"
    }
  }
}

Or copy the JSON directly from the Web UI dashboard.

Authentication

Either:

• Query parameter: ?key=YOUR_API_KEY

• HTTP header: X-Api-Key: YOUR_API_KEY

Available Tools

Image Support

Large images are auto-resized using sharp (pure Node.js, no Electron):

NFS / Network Mounts

The server reads files fresh from the filesystem on every tool call — no caching. NFS mounts work in real-time:

volumes:
  - nfs-vault:/vault

volumes:
  nfs-vault:
    driver: local
    driver_opts:
      type: nfs
      device: ":/path/on/nfs"
      o: addr=10.0.0.1,nfsvers=4

Health Check

curl http://localhost:2768/health

Returns { "status": "ok", "version": "1.1.0" } publicly. Authenticated requests also return vault, port, and sessions.

Building from Source

git clone https://github.com/Alexandre1116/Obsidian-Vault-API-Docker
cd Obsidian-Vault-API-Docker
docker compose build
docker compose up -d

Or without Docker:

npm install
npm run build
VAULT_PATH=/path/to/vault VAULT_API_KEY=secret npm start

Differences from the Original Plugin

License

CC BY-NC-SA 4.0 — same as the original project.