Native sync
Obsidian's official headless client keeps the vault current. The assistant's edits reach your phone and laptop like any other edit.
Without it a copy that drifts, or a desktop app that must stay awake.
Obsidian MCP server · self-hosted
Your vault, in every Claude app.
Claude and ChatGPT read and write your Obsidian notes on your phone, on the web, and on every computer. One container, with sync, sign-in, and note tools built in.
01 Why Crystal Cove
Everything a vault needs. Nothing missing.
An assistant needs three things at once to work well in a vault. Most setups give you two. Crystal Cove puts all three in one container.
Secure sign-in
OAuth, the sign-in flow Claude and ChatGPT connectors expect. Paste your URL, enter one password, and you are connected.
Without it the vault stays on your laptop.
Tools that understand notes
Names, tags, links, backlinks, sections, and frontmatter. The assistant finds the right note and edits one part of it, with fewer tokens than reading raw files.
Without them an assistant that greps a folder.
02 In every app
Ask from anywhere. It lands in Obsidian.
Your phone, a browser, a laptop that isn't yours. The assistant works in the same vault you do, and its edits sync like yours.
Add “call the landlord” to my to-do note.
search_notes “to-do” 1 note
append_note To-do.md done
Added it to your To-do note. It's already on your other devices.
To-do
- Renew passport
- Book the dentist
- Return library books
- Call the landlord
Synced
Works in claude.ai, the Claude apps, Claude Code, and ChatGPT.
03 Security
Your notes on the internet. Locked down.
This server holds your whole knowledge base on a machine that faces the internet. Every design decision starts there.
-
Sign-in, always
Every request needs a token. There is no open mode. OAuth with PKCE, rotating refresh tokens, and a lockout after wrong passwords.
-
The vault and nothing else
Paths cannot escape the vault, and symlinks cannot lead out of it. Tools touch notes only, never Obsidian's settings.
-
Notes stay intact
Writes never overwrite a sync change, and they wait while you type on another device. Deletes go to the trash. A read-only mode removes every write tool.
-
A locked-down container
It runs as a non-root user, with a read-only filesystem and every Linux capability dropped.
-
Checked before it ships
Static analysis, fuzzing, secret scanning, and an image vulnerability scan run on every code change. Every published image is signed.
Check that an image came from this repo before you run it.
cosign verify ghcr.io/dakotahp/crystal-cove:latest \
--certificate-identity-regexp '^https://github.com/dakotahp/crystal-cove/\.github/workflows/(ci|release-please)\.yml@' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comWe list the known limits too. Read them in SECURITY.md
04 Setup
Running in four steps.
You need an Obsidian Sync subscription, Docker, and a server with a domain name. Every command is here.
-
1
Download and sign in
Make a folder and download the compose file.
mkdir crystal-cove && cd crystal-cove curl -O https://raw.githubusercontent.com/dakotahp/crystal-cove/master/docker-compose.ymlSign in to Obsidian Sync, on the machine where the container will run. It asks for your email, password, and MFA code if you have one, then prints a token.
docker run --rm -it ghcr.io/dakotahp/crystal-cove:latest \ sh -c 'ob login && cat ~/.config/obsidian-headless/auth_token'List your vaults to get the name, exactly as Obsidian Sync spells it.
docker run --rm -e OBSIDIAN_AUTH_TOKEN=<your token> \ ghcr.io/dakotahp/crystal-cove:latest ob sync-list-remote -
2
Fill in
.envCreate a
.envfile next todocker-compose.yml.# The token from step 1. OBSIDIAN_AUTH_TOKEN= # The vault name from step 1. OBSIDIAN_VAULTS=Personal # The address your apps will use. HTTPS, with no path. MCP_PUBLIC_URL=https://obsidian.example.com # The password you enter when you connect. 16 characters or more. MCP_OWNER_PASSWORD=End-to-end encrypted vault? Also set
OBSIDIAN_VAULT_PASSWORD. The example file lists every option. -
3
Add HTTPS and start
Put an HTTPS proxy in front of the container. With Caddy, this is the whole configuration. Any reverse proxy or a Cloudflare Tunnel works too.
obsidian.example.com { reverse_proxy localhost:8080 }Start it, and wait for “Fully synced”.
docker compose up -d docker compose logs -f # wait for "Fully synced", then Ctrl-C -
4
Connect
In Claude or ChatGPT, add a custom connector with your URL. A Crystal Cove sign-in page opens. Enter your password, and you are back in the chat, connected.
Only want it on your laptop? It runs locally too.
Full setup guide05 Tools
Tools that read notes the way you do.
Not raw files and folders. Names, sections, tags, and links, so the assistant asks for exactly what it needs.
Read
read_note- Read a note, a page at a time.
read_notes- Read up to 20 notes in one call.
get_section- Read one heading's section.
get_frontmatter- A note's fields and tags, without its body.
list_notes- Browse folders, or the trash.
recent_notes- What changed most recently.
Find
search_notes- Search names and content, ranked.
find_notes- Filter by tags and frontmatter.
list_tags- Every tag, most used first.
get_links- The notes a note links to.
get_backlinks- The notes that link to it.
unresolved_links- Links anywhere in the vault that lead nowhere.
orphans- Notes that no other note links to.
Write
create_note- Make a new note. Never overwrites one.
append_note- Add lines to the end of a note.
edit_note- Exact find and replace.
edit_section- Change one heading's section.
update_frontmatter- Set or remove fields, keeping the rest.
move_note- Rename or move, and can update links. Also restores from the trash.
delete_note- Move a note to the trash.
Want read-only? One setting removes every write tool. Every tool in detail
Your vault, everywhere you ask.
Free and open source, under the MIT License. If it earns a place on your server, a star helps other Obsidian users find it.