Obsidian Vault API — Docker

Which version should I use?

If you are only using the MCP server on your desktop together with Obsidian, use the Obsidian Vault API plugin instead. It runs inside the Obsidian desktop application and is the simpler option for local desktop use.

Use this Docker version, Obsidian Vault API Docker, when you want the MCP server to run 24/7 on a server, NAS, or other always-on machine without requiring the Obsidian desktop app.

• Desktop use with Obsidian open: use Obsidian Vault API.

• 24/7 server or NAS deployment: use this Docker version.

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.

Related MCP server: obsidian-remote-mcp

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.