obsidian-vault-server

Deploys a self-hosted Obsidian vault on a headless Ubuntu server with MCP access over SSH tunnels.

2|Updated Jul 28, 2026
One-click install
npx skills add https://github.com/mbadali25/useful-claude-add-ons --skill obsidian-vault-server-mbadali25
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: obsidian-vault-server
Source: https://github.com/mbadali25/useful-claude-add-ons/tree/main/skills/obsidian-vault-server
Command: npx skills add https://github.com/mbadali25/useful-claude-add-ons --skill obsidian-vault-server-mbadali25

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Obsidian Sync has no headless client, so running a synced vault on a server normally is not possible. This Skill runs the real Obsidian desktop app in a Docker container on Ubuntu, signs it into an obsidian.md account, and exposes the vault to Claude through the obsidian-local-rest-api plugin's built-in MCP endpoint over an SSH tunnel. ## Core Features & Use Cases - Headless server install: Installs Docker, the linuxserver/obsidian KasmVNC container, and the Local REST API plugin, with four Docker Compose fallbacks for hosts where Compose is missing. - Secure access model: Locks down the KasmVNC GUI with ufw and basic auth, and routes both the GUI and the MCP endpoint through SSH tunnels so nothing is published to the network. - Claude MCP integration: Registers the vault with Claude Code or Claude Desktop using the plugin's API key, with guidance on HTTP versus self-signed HTTPS and key rotation. - Use Case: A user wants Claude to read and write notes in a vault that syncs to all their devices but lives on an always-on home server. The Skill walks through install, lockdown, sign-in, finalize, and connecting Claude over a tunnel. ## Quick Start Ask Claude to install and lock down an Obsidian vault server on your Ubuntu host and then connect Claude to it over MCP.

Frequently Asked Questions about obsidian-vault-server

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run Obsidian on a headless server with sync?

Run the real Obsidian desktop app in the linuxserver/obsidian Docker container, which provides a KasmVNC virtual display reachable through a browser. Obsidian Sync only exists in the Electron app, so there is no CLI or daemon alternative.

How do I connect Claude to an Obsidian vault over MCP?

Open an SSH tunnel forwarding port 27123 to the server, then register the obsidian-local-rest-api plugin's /mcp/ endpoint with claude mcp add using the plugin's API key as a Bearer token. The tunnel must be up before Claude resolves the server.

Why does the Obsidian web GUI say a secure connection is required?

KasmVNC uses WebCodecs, which browsers gate behind a secure context, so http://<ip>:3000 refuses to load. Use an SSH tunnel to localhost, which counts as a secure context, or accept the self-signed certificate on https://<ip>:3001.

Why does docker compose plugin not found happen during install?

Docker installed from Ubuntu's docker.io package ships no Compose plugin, so the installer's get.docker.com step is skipped. The installer retries through four fallbacks, but snap-installed Docker cannot load CLI plugins and must be replaced.

Can I copy my workstation's .obsidian folder to the server vault?

No. Copying .obsidian wholesale overwrites the REST API plugin's data.json, which holds the API key, and breaks every connected MCP client. Use the export/apply profile scripts, which treat that file as protected.

Should I use HTTP or HTTPS for the Obsidian MCP endpoint?

Use plain HTTP on port 27123 through the SSH tunnel. The plugin's HTTPS listener on 27124 uses a self-signed certificate that most MCP clients reject, while SSH already encrypts the traffic end to end.